Status updates - Webhooks

Webhook Signature Verification

For security, each webhook request includes a signature header that you should verify to ensure the webhook is sent by our system.

Headers

z-webhook-signature: timestamp:signature

Signature Verification
Use the following code to verify the signature.

Verification Process

Extract the timestamp and signature from the z-webhook-signature header

Recreate the signed body by adding the timestamp to your received payload

Generate the expected signature using your secret

Compare the received signature with the expected signature

Webhook Event Structure

All webhook events follow a consistent structure with these fields:

eventCategory: The category of the event (e.g., "kyc")

eventType: The type of action that occurred (e.g., "transitioned")

eventStatus: The status of the event (varies by event category)

eventObject: The data object containing event-specific details

Example Event

{
  "eventCategory": "kyc",
  "eventType": "transitioned",
  "eventStatus": "approved",
  "eventObject": {
    "entityId": "entity_id",
    "routingId": "routing_id",
    "status": "approved",
    "routingEnabled": true
  }
}

Supported Event Categories and Types

Event Category	Description
`webhook`	Events related to webhook configuration changes
`transfer`	Events related to money transfers in the system
`alm_transaction`	Events related to ALM transfers in the system
`kyc`	Events related to Know Your Customer verification processes

Event Types by Category

Webhook Events

updated: Triggered when your webhook URL is updated

Example:

{
  "eventCategory": "webhook",
  "eventType": "updated",
  "eventStatus": "url_updated",
  "eventObject": {
    "previous": "https://your-domain.com/webhook-endpoint",
    "updated": "https://your-domain.com/webhook-endpoint"
  }
}

Transfer Events

KYC Events

Best Practices

Implement Retry Logic

Your webhook endpoint should return a 2xx status code as quickly as possible. If your server is unable to process the webhook, our system will retry with an exponential backoff.

Verify Signatures

Always verify the webhook signature to ensure the request is coming from our system.

Process Events Idempotently

Events may be delivered more than once in rare circumstances. Design your webhook handler to be idempotent.

Handle Event Object Variations

The eventObject structure may vary according to the event category and type. Your code should be flexible enough to handle these variations.

Monitor Webhook Health

Regularly check that your webhook endpoint is correctly receiving and processing events.

Status updates - Webhooks

Webhook Signature Verification#

Webhook Event Structure#

Supported Event Categories and Types#

Event Types by Category#

Best Practices#

Webhook Signature Verification

Webhook Event Structure

Supported Event Categories and Types

Event Types by Category

Best Practices