Skip to main content

​
How to Add a Webhook

Your system can register to events on the Corsa platform you want to be notified about and act upon.
  1. From the Settings → Developers menu, choose the Webhooks tab and press + Add webhook.
  2. Choose the events you want to receive webhooks for (choose at least one).
  3. Specify your server URL and a secret for validation on your server.

​
Webhook Handling

​
Headers

When receiving webhooks, inspect the following HTTP headers:
HeaderDescription
x-hook-deliveryA unique identifier for this specific delivery attempt.
x-hook-idThe unique identifier of the webhook configuration that sent this request.
x-hook-eventThe type of event that triggered the webhook (e.g., individual_client.created).
x-hub-signature-256The HMAC SHA256 signature of the request payload, used for verifying authenticity.

​
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 = await 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 TypeDescription
individual_client.createdTriggered when an individual client is created.
individual_client.updatedTriggered when an individual client is updated.
corporate_client.createdTriggered when a corporate client is created.
corporate_client.updatedTriggered when a corporate client is updated.

​
Alerts & Cases

Event TypeDescription
alert.createdTriggered when an alert is created.
alert.updatedTriggered when an alert is updated (e.g., status change, assignment, priority change).
case.createdTriggered when a case is created.
case.updatedTriggered when a case is updated (e.g., status change, assignment, investigation update).

​
Transactions

Event TypeDescription
transaction.createdTriggered when a transaction is created.
transaction.updatedTriggered when a transaction is updated (e.g., status change).

​
Financial Operations

Event TypeDescription
deposit.createdTriggered when a deposit operation is created.
deposit.updatedTriggered when a deposit operation is updated.
withdrawal.createdTriggered when a withdrawal operation is created.
withdrawal.updatedTriggered when a withdrawal operation is updated.
trade.createdTriggered when a trade operation is created.
trade.updatedTriggered when a trade operation is updated.

​
Members

Event TypeDescription
individual_member.createdTriggered when an individual member (e.g., beneficial owner, director) is created.
individual_member.updatedTriggered when an individual member is updated.
corporate_member.createdTriggered when a corporate member (e.g., subsidiary, parent company) is created.
corporate_member.updatedTriggered when a corporate member is updated.

​
Financial Instruments

Event TypeDescription
blockchain_wallet.createdTriggered when a blockchain wallet is created.
blockchain_wallet.updatedTriggered when a blockchain wallet is updated (e.g., risk assessment change).
bank_account.createdTriggered when a bank account is created.
bank_account.updatedTriggered when a bank account is updated.
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.

​
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.