Register or Update Webhook URL

Registering or Updating Your Webhook URL

To register or update your webhook URL, use the following endpoint:

PUT /transformer/utility/webhook

Request

{
  "webhookUrl": "https://your-domain.com/webhook-endpoint"
}

Response

{
  "success": true,
  "data": {
    "message": "Webhook URL updated successfully."
  }
}

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
kyc	Events related to Know Your Customer verification processes
transfer	Events related to money transfers in the system
webhook	Events related to webhook configuration changes

Event Types by Category

Each event category has specific event types:

KYC Events

Event Type	Description
transitioned	Triggered when a KYC verification changes status

Example KYC event:

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

KYC Status Values

Status	Description
not_started	The KYC process has not been initiated
initiated	The KYC process has been started but not yet completed
reviewing	KYC information has been submitted and is under review
additional_info_required	Additional information is required to complete the KYC process
rejected	The KYC verification has been rejected
approved	The KYC verification has been approved

Transfer Events

Event Type	Description
transitioned	Triggered when a transfer status changes

Example Transfer Events:

Initial Transaction Creation (Pending)

Triggered when POST /api/v1/transformer/transaction/simulate API is called.

Contains an empty stepDetails object at this stage

Signals the beginning of the transaction execution process

{
  "eventCategory": "transfer",
  "eventStatus": "pending",
  "eventType": "transitioned",
  "eventObject": {
    "entityId": "entity_7fed923d_68e3_425c_9809_8ccfc390f59d",
    "executionId": "exec_5284bb29_9f0c_4480_96af_e771b9df7585",
    "transactionId": "partner_transaction_id_26",
    "transactionStatus": "pending",
    "stepDetails": {}
  }
}

Transaction Execution Started (Processing)

{
  "eventCategory": "transfer",
  "eventStatus": "processing",
  "eventType": "transitioned",
  "eventObject": {
    "entityId": "entity_7fed923d_68e3_425c_9809_8ccfc390f59d",
    "executionId": "exec_15876c4c_e54c_4a5a_a737_5329b37c48e1",
    "transactionId": "partner_transaction_id_28",
    "transactionStatus": "processing",
    "stepDetails": {}
  }
}

Step Completion (Processing)

{
  "eventCategory": "transfer",
  "eventStatus": "processing",
  "eventType": "transitioned",
  "eventObject": {
    "entityId": "entity_7fed923d_68e3_425c_9809_8ccfc390f59d",
    "executionId": "exec_1a880a1a_01c1_4314_8f51_6f06ed51618b",
    "transactionId": "partner_transaction_id_21",
    "transactionStatus": "processing",
    "stepDetails": {
      "name": "Awaiting Fiat Deposit",
      "status": "completed",
      "currentStep": 1,
      "totalSteps": 3
    }
  }
}

Transaction Completion

{
  "eventCategory": "transfer",
  "eventStatus": "completed",
  "eventType": "transitioned",
  "eventObject": {
    "entityId": "entity_7fed923d_68e3_425c_9809_8ccfc390f59d",
    "executionId": "exec_1a880a1a_01c1_4314_8f51_6f06ed51618b",
    "transactionId": "partner_transaction_id_21",
    "transactionStatus": "completed",
    "stepDetails": {
      "name": "Making Transfer to Beneficiary",
      "status": "completed",
      "currentStep": 3,
      "totalSteps": 3
    }
  }
}

Transaction Status Values

Status	Description
pending	The transaction has been created via the simulate API but not yet executed
processing	The transaction is being executed and steps are in progress
completed	The transaction has been successfully completed
failed	The transaction has failed due to an error in one of the steps

Step Status Values

Status	Description
completed	The step has been successfully completed
failed	The step has failed due to an error

NOTE - Originally the step has the following statuses: pending, processing, completed, and failed. However, webhooks will only be triggered for completed and failed statuses.

Webhook Events

Event Type	Description
updated	Triggered when your webhook URL is updated

Example webhook event:

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

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.

Register or Update Webhook URL

Request#

Response#

Webhook Signature Verification#

Webhook Event Structure#

Supported Event Categories and Types#

Event Types by Category#

KYC Events#

KYC Status Values#

Transfer Events#

Transaction Status Values#

Step Status Values#

Webhook Events#

Best Practices#

Request

Responses

Request

Response

Webhook Signature Verification

Webhook Event Structure

Supported Event Categories and Types

Event Types by Category

KYC Events

KYC Status Values

Transfer Events

Transaction Status Values

Step Status Values

Webhook Events

Best Practices