Webhooks

Webhooks are a way for Crezco to notify your application in real time when important events occur, such as status changes to pay runs, payables, or organisations. Instead of polling the API for updates, you can register a webhook endpoint to receive event notifications automatically via HTTP POST requests. This enables you to keep your systems up to date and respond quickly to changes.

How Webhooks Work

Register your endpoint via the API, specifying which event types you want to receive.
Receive HTTP POST requests at your endpoint whenever a relevant event occurs.
Acknowledge receipt by returning a 200 OK response. If not, Crezco will retry delivery.

Event Types

Crezco supports several event types, including:

PayRun: Status changes to a pay run
Payable: Status changes to a payable
OrganisationOnboarding: Organisation onboarding status
BankAccount: Bank account status changes
Verification: KYC/KYB verification status

Refer to the API documentation for a full list and details of event types.

Registering an Endpoint

To receive webhooks, register your endpoint using the API. Your registration must:

Specify at least one event type
Use a unique HTTPS URL (TLS 1.2+)
Not include query parameters

Example registration payload:

{
  "eventType": "PayRun",
  "callback": "https://webhooks.example.org/crezco/payruns",
  "version": "2024-06-30"
}

Payload Structure

Webhook payloads are sent as JSON and may contain multiple events. Example:

{
  "events": [
    {
      "eventId": "...",
      "type": "Payable",
      "id": "...",
      "status": "UserInitiationInProgress",
      "timestamp": "2024-06-28T20:16:07.164Z",
      "organisationId": "...",
      "version": "2024-06-30",
      "payload": {
        /* additional info */
      }
    }
  ]
}

See the API documentation for a full list of fields and their meanings.

Delivery and Retries

Your endpoint must respond with 200 OK within 5 seconds.
Non-200 or timeout responses will trigger retries with exponential backoff for up to 48 hours.
Payloads may be delivered more than once or out of order—handle idempotency and ordering in your system.

Security and Signature Verification

Each webhook request includes headers for signature verification:

Crezco-Signature: SHA256 signature of the payload
Date: Timestamp of the request
Crezco-Public-Key-Id: ID of the public key used

You should verify all incoming webhooks using the public key from the API. If verification fails, respond with 401 Unauthorized.

Best Practices

Always verify webhook signatures
Make your endpoint idempotent and resilient to duplicate/out-of-order events
Monitor and log webhook deliveries and failures
Use tools like webhook.site for testing