Create a webhook endpoint in your app
Your webhook handler must:
- Accept
POSTrequests at a public HTTPS URL - Read the raw request body (before JSON parsing) for signature verification
- Return
HTTP 200within 5 seconds - Process event logic asynchronously after returning 200
- TypeScript (Express)
- Python (Flask)
- PHP
TypeScript
Register the webhook with Yativo
Register your endpoint and select which event types you want to receive.Response:
Verify webhook signatures
Every webhook request includes an
X-Webhook-Signature header containing an HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret.Always verify this signature before processing the event.- TypeScript
- Python
- PHP
TypeScript
Handle events idempotently
The same event may be delivered more than once (see Retry Policy below). Your handler must be idempotent — processing the same event twice should produce the same result as processing it once.
TypeScript
Return 200 quickly and process asynchronously
Yativo waits up to 5 seconds for an HTTP 200 response. If your server does not respond in time, the delivery is treated as failed and will be retried.Pattern: Respond 200 first, then process.In production, use a job queue (e.g., BullMQ, Celery, SQS) rather than
TypeScript
setImmediate so events survive server restarts.Understand the retry policy
If your endpoint returns a non-2xx status code, times out, or is unreachable, Yativo retries the delivery with exponential backoff:
After 7 failed attempts, the event is marked as permanently failed and no further retries are made. You can manually replay failed events from the Dashboard or via
| Attempt | Delay after previous |
|---|---|
| 1 (initial) | — |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 6 hours |
| 7 | 24 hours |
POST /webhook/{webhookId}/replay.Because retries are possible, your handlers must be idempotent (see Step 4). A 200 response stops retries — never return 200 if you have not processed (or enqueued) the event.
Event Types Reference
Wallet & Deposit Events
| Event | Description |
|---|---|
deposit.detected | A deposit transaction was seen on-chain (unconfirmed) |
deposit.confirmed | Deposit has sufficient confirmations — safe to credit |
deposit.failed | A detected deposit was not confirmed (e.g., dropped from mempool) |
Transaction Events
| Event | Description |
|---|---|
transaction.pending | Outbound transaction created and queued |
transaction.broadcasting | Being submitted to the blockchain |
transaction.confirmed | Transaction confirmed on-chain |
transaction.failed | Transaction failed; funds returned to account |
Swap Events
| Event | Description |
|---|---|
swap.initiated | Swap execution started |
swap.completed | Destination asset arrived in account |
swap.failed | Swap failed; see failureReason |
swap.refunded | Swap failed after source funds left; original asset returned |
Card Events
| Event | Description |
|---|---|
card.transaction.approved | Authorization approved |
card.transaction.declined | Authorization declined (includes declineReason) |
card.transaction.completed | Settlement cleared |
card.transaction.reversed | Transaction reversed or refunded |
card.funding.completed | Card top-up completed |
card.spending_limit.reached | Card spending limit hit |
KYC & Customer Events
| Event | Description |
|---|---|
kyc.status_changed | KYC status updated (includes new status) |
customer.kyc.approved | Customer KYC approved (issuer program) |
customer.kyc.rejected | Customer KYC rejected |
IBAN Events
| Event | Description |
|---|---|
iban.activated | IBAN account is active and ready to receive |
iban.transfer.received | Incoming bank transfer detected |
iban.transfer.converted | Transfer converted to crypto |
Issuer Program Events
| Event | Description |
|---|---|
card_issuer.application_approved | Issuer program application approved |
card_issuer.application_rejected | Issuer program application rejected |
card_issuer.limit_warning | Approaching program volume limits |
Webhook Event Envelope
All events share a common envelope:| Field | Type | Description |
|---|---|---|
eventId | string | Unique event ID — use for idempotency |
type | string | Event type |
webhookId | string | ID of the registered webhook |
createdAt | ISO 8601 | When the event was generated |
attempt | integer | Delivery attempt number (starts at 1) |
data | object | Event-specific payload |
Managing Webhooks
TypeScript

