Webhooks

​

What to do on each event

​

How delivery works

​

Event types

created → funded → completed
    ↓        ↓
  failed   refunded
    ↓
 canceled

created → funded → completed → finalized
    ↓        ↓
  failed   failed
    ↓
 canceled

created → funded → completed
    ↓        ↓
  failed   failed

​

Payloads

• order_updated carries burnTransaction, depositClabe, and confirmedTxSignature only when relevant to the order type and status. For embedded (non-custodial) wallets it also carries the pending approval object (approvalMessageId, approvalMessage, summary) while the order awaits the owner’s signature; there is no separate embedded-wallet transaction event. Re-read the order right before signing so the approvalMessage timestamp is fresh.
• swap_updated — sendTransaction is always present (the transaction to sign; it stays in the payload but is no longer actionable once signed); receiveTransactionHash appears only on completion.
• bank_account_updated — while compliant is false the customer must complete additional verification before the bank can be used; the form depends on the bank type (see Bank account compliance).
• kyc_updated — on approval, approved is true and updateReason / needsWork / userMessage are omitted.
• kyb_updated carries the business’s organizationId and status. It fires only when the status actually changes, never on individual answer edits. The approved / submitted / notStarted / total counts cover the customer-facing requirements only, and approvedAt is set once the business is approved.

​

Reliability & best practices

• Retries. Failed deliveries (a non-2xx response or connection error) are retried up to 3 times with 5-second delays. Return a 2xx promptly to avoid them.
• Acknowledge fast, process async. Hand the payload to a queue and return 2xx right away; don’t block the response on downstream work.
• Handle events idempotently. The same event can arrive more than once (e.g. a retry after your 2xx was lost). Dedupe on the resource ID plus its status so reprocessing is harmless — this pairs naturally with the client-generated UUIDs you already use for orders.
• Don’t rely on ordering. Drive your logic off the status in the payload, not the order in which deliveries arrive.
• Expose a public HTTPS endpoint. For local development, use a tunnel such as ngrok so Etherfuse can reach your handler.

​

Verifying signatures

​

Managing webhooks

• Create a subscription — POST /ramp/webhook (returns the one-time secret)
• List subscriptions — POST /ramp/webhooks
• Get a subscription — GET /ramp/webhook/{id}
• Delete a subscription — DELETE /ramp/webhook/{id}