Webhooks

Caliza sends webhook notifications to your application in real time as events occur throughout the lifecycle of transactions, beneficiaries, and payments. Webhooks allow you to react immediately to status changes without polling our API.

When an event occurs, we send an HTTP POST request to the callback URL you have configured, with a JSON payload describing the event. Each request includes an HMAC-SHA256 signature so you can verify its authenticity.

Setting up your webhook URL

Configure the URL where you want to receive webhook notifications:

Update your webhook URL by calling PATCH /v1/integrators/{integratorId}/webhooks with your endpoint URL
Retrieve your current webhook URL by calling GET /v1/integrators/{integratorId}/webhooks

Managing your webhook secret

Each webhook request is signed with a secret key unique to your integration. To manage your secret:

View your webhook secret in the Backoffice under Avatar Icon > Profile Page
Regenerate your secret by calling POST /v1/integrators/{integratorId}/update-webhook-secret
Retrieve your encrypted secret by calling GET /v1/integrators/{integratorId}/webhook-secret

For details on verifying webhook signatures, see the Signature Validation Guide.

Webhook payload

Every webhook notification follows the same structure:

{
  "operation": "TRANSACTION_COMPLETED",
  "resourceId": "632a208b-806b-d700-9719-7367a1b2c3d4",
  "createdAt": "2024-09-20T17:20:28.935890",
  "integratorId": "6306548828912548710e667c",
  "beneficiaryId": "6306556b28912548710e667e",
  "message": null,
  "success": true,
  "data": { }
}

Field	Type	Description
`operation`	string	The event type that triggered this webhook. See Webhook Events for the full list.
`resourceId`	string	The unique identifier of the resource associated with this event (e.g., transaction ID, beneficiary ID).
`createdAt`	string	ISO 8601 timestamp of when the event occurred.
`integratorId`	string	Your integrator identifier.
`beneficiaryId`	string	The beneficiary associated with this event, if applicable.
`message`	string	Additional context about the event. May be `null`.
`success`	boolean	`true` if the operation succeeded, `false` if it failed.
`data`	object	Additional details about the event. Contents vary by operation type.

Signature header

Every webhook request includes the following header:

Header	Description
`X-Caliza-Webhook-Signature`	Base64-encoded HMAC-SHA256 signature of the raw request body, computed using your webhook secret.

Always verify this signature before processing a webhook. See the Signature Validation Guide for implementation examples.

Best practices

Always verify signatures. Validate the X-Caliza-Webhook-Signature header on every request using your webhook secret before processing the payload.
Respond quickly. Return a 200 status code as soon as you receive the webhook. Perform any heavy processing asynchronously after acknowledging receipt.
Handle duplicates. In rare cases, the same event may be delivered more than once. Use the resourceId and operation combination to deduplicate.
Use HTTPS. Always configure an HTTPS endpoint for your webhook URL to ensure payloads are encrypted in transit.
Rotate secrets regularly. Periodically regenerate your webhook secret via POST /v1/integrators/{integratorId}/update-webhook-secret and update your verification logic accordingly.

Next steps

Webhook Events

Full reference of all event types, payload examples, and events by payment corridor.

Signature Validation Guide

Implementation examples for verifying webhook signatures.