Unified Envelope Format
All webhooks share the same outer structure:
{
"event": "<event_name>",
"timestamp": "2026-03-22T10:00:00+07:00",
"data": { }
}
| Field | Type | Description |
|---|---|---|
| event | string | The event name that triggered this webhook |
| timestamp | string | Webhook dispatch timestamp (ISO 8601) |
| data | object | Event-specific payload (see individual event docs) |
Webhook Registration
Webhook endpoints are configured during client onboarding or can be set up later via the admin panel. Each event type requires a separate webhook configuration with:
- Base URL (e.g., https://yourdomain.com)
- Path (e.g., /api/webhooks/payment)
The complete webhook URL is built as: {base_url}{path}
Event names follow a structured naming convention: payment.v2.completed, disbursement.v2.completed, etc. Register each event independently.
Response Requirements
Your webhook endpoint must return a standard HTTP status code:
- 200-299: Success (webhook handled successfully)
- 4xx: Client error (retries will not be attempted, except 408 and 429 — see Error Handling)
- 5xx: Server error (retries will be attempted)
Keep response time under 5 seconds to prevent timeout.
Idempotency
Request Headers
All webhook requests include these authentication headers:
| Header | Description |
|---|---|
| X-PARTNER-ID | Your client identifier |
| X-TIMESTAMP | Request timestamp in ISO8601 format (e.g., 2024-12-18T16:21:07+07:00) |
| X-SIGNATURE | RSA signature for request verification (see Signature Generation) |
Security Best Practices
- Always validate the X-SIGNATURE header to authenticate requests
- Confirm the X-PARTNER-ID matches your client ID
- Validate the X-TIMESTAMP to prevent replay attacks
- Use HTTPS for your webhook endpoint
- Implement idempotency checks using identifiers inside
datato prevent duplicate processing
Events
| Event | Description |
|---|---|
payment.v2.completed |
Payment is successfully completed |
disbursement.v2.completed |
Disbursement is successfully completed |
disbursement.v2.fail |
Disbursement fails |
disbursement.v2.expired |
Disbursement expires |
transaction_settlement.settled |
A transaction settlement is finalised and funds are transferred |
Error Handling
If your endpoint returns a non-2xx status code or times out:
- 5xx responses: retried (up to 3 attempts total, including the first, with 10-second and 30-second delays between retries)
- 408 (Request Timeout) and 429 (Too Many Requests): also retried, on the same schedule as 5xx
- Other 4xx responses: No retry will be attempted — review your endpoint logic
- Timeout (> 5 seconds): Treated as a failure and retried. The 5-second timeout applies per attempt — each retry gets a fresh window, not a cumulative budget across all 3 attempts.
- Connection errors (connection refused, DNS failure, SSL errors, unreachable host): also treated as a failure and retried, same as the cases above.
Ensure your webhook handler processes quickly and offloads heavy work asynchronously.