Webhooks

How to Add a Webhook

Your system can register to events on the Corsa platform you want to be notified about and act upon.

From the Settings → Developers menu, choose the Webhooks tab and press + Add webhook.
Choose the events you want to receive webhooks for (choose at least one).
Specify your server URL and a secret for validation on your server.

Webhook Handling

Headers

When receiving webhooks, inspect the following HTTP headers:

Header	Description
`x-hook-delivery`	A unique identifier for this specific delivery attempt.
`x-hook-id`	The unique identifier of the webhook configuration that sent this request.
`x-hook-event`	The type of event that triggered the webhook (e.g., `individual_client.created`).
`x-hub-signature-256`	The HMAC SHA256 signature of the request payload, used for verifying authenticity.
`x-request-id`	Request trace ID for debugging and correlating logs.
`x-request-origin`	Origin of the request that triggered the event (`WEB` or `API`).

Verifying Signatures

It’s crucial to verify the signature of incoming webhooks to ensure they originated from the Corsa API and were not tampered with. Use the verifyWebhookSignature function exported from the SDK.

import { verifyWebhookSignature } from '@corsa-labs/sdk';

async function verifyWebhookRequest(request: Request) {
  const signature = request.headers.get('x-hub-signature-256');
  const payload = await request.text();
  const secret = process.env.WEBHOOK_SECRET;

  if (!signature || !secret) {
    console.error("Missing signature or secret");
    return false;
  }

  const isValid = verifyWebhookSignature(secret, payload, signature);

  if (!isValid) {
    console.error('Invalid webhook signature');
    return false;
  }

  console.log("Webhook signature verified successfully!");
  return true;
}

Event Types

The following webhook event types are available (defined in WebhookEventType):

Clients

Event Type	Description
`individual_client.created`	Triggered when an individual client is created.
`individual_client.updated`	Triggered when an individual client is updated.
`corporate_client.created`	Triggered when a corporate client is created.
`corporate_client.updated`	Triggered when a corporate client is updated.

Alerts & Cases

Event Type	Description
`alert.created`	Triggered when an alert is created.
`alert.updated`	Triggered when an alert is updated (e.g., status change, assignment, priority change).
`case.created`	Triggered when a case is created.
`case.updated`	Triggered when a case is updated (e.g., status change, assignment, investigation update).

Transactions

Event Type	Description
`transaction.created`	Triggered when a transaction is created.
`transaction.updated`	Triggered when a transaction is updated (e.g., status change).

Financial Operations

Event Type	Description
`deposit.created`	Triggered when a deposit operation is created.
`deposit.updated`	Triggered when a deposit operation is updated.
`withdrawal.created`	Triggered when a withdrawal operation is created.
`withdrawal.updated`	Triggered when a withdrawal operation is updated.
`trade.created`	Triggered when a trade operation is created.
`trade.updated`	Triggered when a trade operation is updated.

Members

Event Type	Description
`individual_member.created`	Triggered when an individual member (e.g., beneficial owner, director) is created.
`individual_member.updated`	Triggered when an individual member is updated.
`corporate_member.created`	Triggered when a corporate member (e.g., subsidiary, parent company) is created.
`corporate_member.updated`	Triggered when a corporate member is updated.

Financial Instruments

Event Type	Description
`blockchain_wallet.created`	Triggered when a blockchain wallet is created.
`blockchain_wallet.updated`	Triggered when a blockchain wallet is updated (e.g., risk assessment change).
`bank_account.created`	Triggered when a bank account is created.
`bank_account.updated`	Triggered when a bank account is updated.
`payment_account.created`	Triggered when a payment account (PIX, CLABE, mobile money, etc.) is created.
`payment_account.updated`	Triggered when a payment account is updated.

Checklists

Event Type	Description
`checklist.created`	Triggered when a checklist is created for an entity.
`checklist.updated`	Triggered when a checklist or checklist item is updated.

Attachments

Event Type	Description
`attachment.created`	Triggered when a file attachment is uploaded or linked to an entity.
`attachment.updated`	Triggered when an attachment’s metadata is updated.
`attachment.deleted`	Triggered when an attachment is deleted.

Forms

Event Type	Description
`form_template.public_form_submitted`	Triggered when a client submits a form.

The payload structure for each event type (WebhookEvent, EntityCreatedPayload, EntityUpdatedPayload) and the WebhookEventType enum can be imported from @corsa-labs/sdk. For detailed payload structures for each event type, see the Event Payloads reference. For a practical example of how to set up a webhook handler, see the Webhook Example.

Retries & Failure Handling

Corsa retries failed webhook deliveries automatically. A queued delivery attempt is considered failed if your endpoint returns a non-2xx status code or does not respond within 5 seconds.

Queued attempt	Delay after previous attempt
1 (initial)	Immediate
2	10 seconds
3	10 seconds
4	10 seconds

After the initial attempt and three queued retries fail, the delivery is marked as failed. Redirects are not followed, so your endpoint must return a 2xx response directly. Because retries can deliver the same event more than once, your handler should be idempotent — use the x-hook-delivery header as a unique key to deduplicate events on your side.

Signing Secret

The signing secret is a shared string used to verify that incoming webhook requests are authentic and have not been tampered with or spoofed. This ensures that the request is genuinely coming from the Corsa server. Make sure the signing secret you provide is stored securely and encrypted in your platform (for example, using AWS Secrets Manager). We use HMAC-based shared-key authentication. The signing process involves generating a signature using the shared key and comparing it with the one included in the webhook request.

const signingSecret: string = '<the secret>';
const algorithm = 'sha256';
const result = `${algorithm}=${createHmac(algorithm, signingSecret)
    .update(payload)
    .digest('hex')}`;

// >>> console.log(result)
// sha256=4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865

The result is attached in the request headers under the X-Hub-Signature-256 header:

X-Hub-Signature-256: sha256=4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865

On your end, validate by using the same implementation (hashing the HTTP request body) and compare the result with the header. For increased security, use a cryptographically-secure string comparison function like crypto.timingSafeEqual.

API

AI Skills

Javascript

Python

HYOK

Webhooks - Real-Time Compliance Event Notifications

How to Add a Webhook

Webhook Handling

Headers

Verifying Signatures

Event Types

Clients

Alerts & Cases

Transactions

Financial Operations

Members

Financial Instruments

Checklists

Attachments

Forms

Retries & Failure Handling

Signing Secret

​How to Add a Webhook

​Webhook Handling

​Headers

​Verifying Signatures

​Event Types

​Clients

​Alerts & Cases

​Transactions

​Financial Operations

​Members

​Financial Instruments

​Checklists

​Attachments

​Forms

​Retries & Failure Handling

​Signing Secret

How to Add a Webhook

Webhook Handling

Headers

Verifying Signatures

Event Types

Clients

Alerts & Cases

Transactions

Financial Operations

Members

Financial Instruments

Checklists

Attachments

Forms

Retries & Failure Handling

Signing Secret