What are Webhooks?
Webhooks let you receive real-time HTTP notifications when funding account, deposit, transfer, withdrawal, or customer verification lifecycle events occur, instead of polling the API for status changes.Webhooks are the recommended way to track funding account provisioning, deposit settlement, merchant-initiated bank transfers, crypto withdrawal progress, and customer verification changes.
Supported Events
Deposit Events:| Event | Resource | Description |
|---|---|---|
deposit.received | Deposit | Deposit received (NGN or crypto) |
deposit.processing | Deposit | Deposit settlement has started |
deposit.requires_review | Deposit | Deposit needs review before it can continue |
deposit.completed | Deposit | Deposit reached its settlement destination |
deposit.failed | Deposit | Deposit failed |
deposit.reversed | Deposit | Completed deposit reversed |
| Event | Resource | Description |
|---|---|---|
funding_account.created | Funding Account | Funding account record created in pending state |
funding_account.active | Funding Account | Receive instructions provisioned successfully |
funding_account.failed | Funding Account | Receive instruction provisioning failed |
funding_account.disabled | Funding Account | Funding account disabled |
| Event | Resource | Description |
|---|---|---|
withdrawal.created | Withdrawal | Withdrawal request accepted |
withdrawal.submitted | Withdrawal | Withdrawal submitted to chain |
withdrawal.completed | Withdrawal | Withdrawal confirmed on-chain |
withdrawal.failed | Withdrawal | Withdrawal failed |
| Event | Resource | Description |
|---|---|---|
transfer.created | Transfer | Transfer record created |
transfer.processing | Transfer | Funds locked and transfer submission queued |
transfer.requires_review | Transfer | Transfer flagged for manual review |
transfer.submitted | Transfer | Provider accepted the transfer submission |
transfer.completed | Transfer | Transfer settled after provider success and ledger finalization |
transfer.failed | Transfer | Transfer failed terminally |
transfer.reversed | Transfer | Completed transfer reversed |
| Event | Resource | Description |
|---|---|---|
customer.verification.submitted | Customer | Verification submitted for review |
customer.verification.approved | Customer | Verification approved |
customer.verification.rejected | Customer | Verification rejected |
Use
transfer.* events for POST /v1/transfers. For deposits, track settlement with deposit.* events; settlement delivery work that Daya performs in the background is not surfaced as a separate payout webhook.Webhook Configuration
Configure webhook endpoints in your Daya Dashboard:- Navigate to Webhooks
- Add your webhook URL
- Generate or copy your webhook secret
- Subscribe to the events you want to receive
event_types setting controls which events an endpoint receives. Omit event_types or set it to [] to receive all events. Use a non-empty array, such as ["deposit.received", "deposit.completed"], to receive only those exact event names. Unknown event names are rejected.
Webhook Payload
All merchant webhooks use the same envelope:Common Fields
Event type, such as
deposit.completed, transfer.completed, or withdrawal.failed.Unique webhook event identifier. Store this value to deduplicate deliveries.
Resource payload for the event. Funding account events send a funding account object, deposit events send a deposit object, transfer events send a transfer object, withdrawal events send a withdrawal object, and customer verification events send a customer object.
RFC3339 timestamp for when the event was emitted.
Delivery Guarantees
At-least-once delivery
At-least-once delivery
Webhooks may be delivered more than once. Your handler must deduplicate repeated deliveries.
Order not guaranteed
Order not guaranteed
Events can arrive out of order. Use the
timestamp field to order updates client-side.Retry behavior
Retry behavior
If your endpoint returns a non-2xx response or times out, Daya retries with backoff. Build your handler to be safe for repeated delivery.
Timeout
Timeout
Respond quickly and offload heavy work asynchronously. Slow handlers increase duplicate deliveries.
Webhook Verification
All webhook requests include an HMAC-SHA256 signature in theX-Daya-Signature header.
See Webhook Verification for implementation details.
Implementing a Webhook Endpoint
Your endpoint should:- Verify the signature
- Build a stable deduplication key from the payload
- Return
2xxquickly - Process the event asynchronously if work is non-trivial
Best Practices
Handle out-of-order events
Use
timestamp and the underlying resource state to reconcile event order safely.Testing Webhooks
For deposit webhook flows:- Create a sandbox receive instruction
- Trigger a sandbox deposit with Create a sandbox deposit
- Observe the resulting deposit lifecycle webhooks
- Fund merchant balance through a merchant-balance settlement flow
- Create a withdrawal
- Observe
withdrawal.created,withdrawal.submitted,withdrawal.completed, orwithdrawal.failed
Troubleshooting
Webhooks not received
Webhooks not received
Check endpoint reachability, TLS configuration, and whether your handler is returning non-2xx responses.
Duplicate deliveries
Duplicate deliveries
Duplicate delivery is expected under at-least-once semantics. Deduplicate using the webhook event
id.Out-of-order events
Out-of-order events
Sort or reconcile events using
timestamp instead of arrival order.Signature verification fails
Signature verification fails
Verify you are using the correct webhook secret and the raw request body.
Next Steps
Webhook Events
Event inventory and resource payload mapping
Signature Verification
Implement HMAC verification