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

1. Register your endpoint via the API, specifying which event types you want to receive.
2. Receive HTTP POST requests at your endpoint whenever a relevant event occurs.
3. 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