Skip to main content

Overview

All webhook deliveries share a common JSON envelope. Register for specific event types when creating a webhook endpoint.

Signature Verification

Each request carries an X-Fyatu-Signature header in the format t=<unix_timestamp>,v1=<hex_hmac>. The HMAC is SHA-256 over "<timestamp>.<raw_request_body>" using your webhook signing secret as the key.
Node.js
Reject any delivery where verification fails or the timestamp is older than 5 minutes.

Account Events

Withdrawal payloads

All three carry withdrawalId, programId, amount, token, network and toAddress.
transactionHash cannot be known when a withdrawal is accepted, because nothing has been broadcast at that point. Expect ACCOUNT_WITHDRAWAL_INITIATED without a hash, and ACCOUNT_WITHDRAWAL_COMPLETED with one, some time later.

Billing Events

Deposit payloads

Both deposit events carry the chain detail, so a transfer can be reconciled against a block explorer without asking us anything: DETECTED carries no balance, because nothing has been credited at that point. A field is omitted rather than sent empty when we do not hold it.
BILLING_DEPOSIT_CONFIRMED means the deposit reached your balance. Do not read it as “N confirmations observed”; use transactionHash to check the transfer on a block explorer.

Cardholder Events


Card Events


Transaction Events

TRANSACTION_PROCESSED is the single event for the card-charge lifecycle. A card charge is delivered as one event with status: COMPLETED (or REVERSED when the charge was reversed/refunded, ADJUSTED for an FX settlement adjustment). There is no separate authorization-then-settlement pair — subscribe to TRANSACTION_PROCESSED and branch on status.
TRANSACTION_PROCESSED payload
Deprecated transaction events. TRANSACTION_AUTHORIZED, TRANSACTION_CLEARED, and TRANSACTION_REVERSED are deprecated in favor of TRANSACTION_PROCESSED. They remain fully supported — existing integrations subscribed to them continue to receive deliveries unchanged, so no action is required. New integrations should subscribe to TRANSACTION_PROCESSED.

Delivery & Retry Policy

Return 200 OK immediately and process the webhook asynchronously. Slow handlers that exceed the timeout trigger retries, which may cause duplicate processing.