Overview
All webhook deliveries share a common JSON envelope. Register for specific event types when creating a webhook endpoint.Signature Verification
Each request carries anX-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
Account Events
Withdrawal payloads
All three carrywithdrawalId, 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.
