Create a webhook endpoint in your app
Your webhook handler must:
- Accept
POSTrequests at a public HTTPS URL - Parse the JSON body and verify the
X-Yativo-Signature+X-Yativo-Timestampheaders before processing - 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 delivery includes two headers:
The HMAC is computed over
| Header | Value |
|---|---|
X-Yativo-Signature | sha256=<hmac> |
X-Yativo-Timestamp | Unix timestamp (seconds) |
"${timestamp}.${JSON.stringify(payload)}". 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 deliveries 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 /v1/yativo-card/webhooks/deliveries/:deliveryId/retry.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
Deposit Events
| Event | Description |
|---|---|
deposit.detected | A deposit transaction was seen on-chain (unconfirmed) |
deposit.confirmed | Deposit has sufficient confirmations — safe to credit |
Transaction Events
| Event | Description |
|---|---|
transaction.initiated | Outbound transaction created and queued |
transaction.submitted | Transaction broadcast to the network |
transaction.failed | Transaction failed; funds returned to account |
transaction.{type}.completed | A transaction of the given type completed (e.g. transaction.withdrawal.completed) |
Card Events
Card issuer events and general crypto events share the same webhook service. Register atPOST /v1/webhook/create-webhook and include the relevant card event slugs in your events array.
| Event | Description |
|---|---|
card.created | A card was issued |
card.activated | A card was activated (physical cards) |
card.frozen | A card was frozen |
card.unfrozen | A frozen card was re-enabled |
card.lost | A card was marked lost |
card.stolen | A card was reported stolen |
card.voided | A card was voided |
card.cancelled | A card was cancelled |
card.deactivated | A card was permanently deactivated |
transaction.authorized | A card transaction was authorized |
transaction.declined | A card transaction was declined |
transaction.settled | A card transaction settled |
transaction.reversed | A card transaction was reversed |
transaction.refund.created | A refund was initiated |
customer.funded | A customer’s card wallet was credited |
customer.funding.failed | A funding transfer failed |
customer.balance.updated | A customer’s card balance changed |
master_wallet.deposit | Funds arrived in the card program master wallet |
master_wallet.swap | A swap executed in the master wallet |
master_wallet.customer_funded | Master wallet funds allocated to a customer |
IBAN Events
| Event | Description |
|---|---|
iban.activated | IBAN account is active and ready to receive |
iban.transfer.received | Incoming bank transfer detected |
KYC Events
| Event | Description |
|---|---|
kyc.submitted | A KYC submission was received |
kyc.approved | KYC was approved |
kyc.rejected | KYC was rejected |
kyc.pending_review | KYC is awaiting manual review |
Webhook Event Envelope
All events share a common envelope. The request body is JSON; delivery metadata is carried in HTTP headers. Request body:| Header | Value |
|---|---|
X-Yativo-Signature | sha256=<hmac> — use this to verify authenticity |
X-Yativo-Timestamp | Unix timestamp (seconds) — included in the HMAC |
X-Yativo-Event | Event type string (e.g. deposit.confirmed) |
X-Yativo-Delivery-Id | Unique delivery ID for this attempt |
| Field | Type | Description |
|---|---|---|
id | string | Unique event ID — use for idempotency |
type | string | Event type |
created_at | ISO 8601 | When the event was generated |
data | object | Event-specific payload |

