Webhooks
Swapper sends a signed, server-to-server webhook when a deposit completes. Use it as your reliable source of truth for crediting accounts — unlike a widget event, a webhook isn't lost when the user closes the tab, and it's retried on failure.
Webhooks cover deposits made through the widget and transfers quoted through API v1. A v1 transfer is recorded — and its webhook sent — once it has been tracked, so API integrations should keep polling GET /v1/status after the user broadcasts; v1 transfers arrive with method: "dex_swap" (and so flow: "wallet_deposit"). Deposits to a v1 deposit address arrive with flow: "transfer_crypto", like the widget's QR deposits — identify them by flow, as their method can change.
Setup
Configure webhooks yourself in the Integrator Dashboard, under Webhooks (owners only):
Add your endpoint URL(s) — up to 5. Every event is sent to each of them.
Generate a signing secret and store it on your server. Every delivery is then signed with it (see Verifying the signature). Without a secret, deliveries are sent unsigned.
Watch Recent deliveries on the same page to confirm events are going out.
Webhooks are configured per integrator, not per widget session.
Your endpoint must be:
served over HTTPS on a public host (private and local addresses are refused);
publicly reachable from the internet;
fast — return HTTP 2xx within 10 seconds (slow responses count as a failure and trigger a retry);
answering at the configured URL — only
307/308redirects are followed (up to 3, each to a public host). Any other redirect (301,302,303) counts as a failed delivery, so configure the final URL.
app.post("/webhooks/deposit", (req, res) => {
const { eventId, eventType, data } = req.body;
const { deposit } = data;
console.log("Deposit completed:", deposit.id, deposit.txHash);
res.json({ received: true });
});The request
Each delivery is an HTTP POST with these headers:
Content-Type
application/json
User-Agent
Swapper-Deposits-Webhook/1.0
X-Webhook-Signature
Base64 HMAC-SHA256 of the body — present when you have a signing secret.
The event
transaction.completed is the only event type. You are notified once, when a deposit completes — there are no created / processing / failed events.
Top-level fields
eventId
string
Unique event id — use for idempotency.
eventType
string
Always transaction.completed.
timestamp
string
ISO 8601 timestamp of the event.
data.deposit
Deposit
The deposit (below).
data.integratorId
string
Your integrator id.
Deposit object
id
string
Unique deposit id.
method
string
How the deposit was settled: onramp | smart_wallet | dex_swap | deposit_address (see methods).
flow
string?
The widget flow the deposit came from: deposit_with_fiat | transfer_crypto | wallet_deposit.
status
string
Lifecycle status — completed on this event.
integratorId
string
Your integrator id.
source
Asset
What went into the swap.
deposited
Asset?
What the user originally deposited (smart_wallet).
destination
Asset?
What was delivered on the destination chain.
depositTxHash
string?
onramp: the on-chain tx that delivered crypto into the smart wallet. deposit_address: the user's transfer into the deposit address — the hash they see in their wallet or exchange history.
fundingTxs
string[]?
smart_wallet only — every on-chain tx that funded the swap.
txHash
string?
Source-chain swap tx hash. For deposit_address, the transaction that swept the deposit address.
destinationTxHash
string?
Destination-chain tx hash (cross-chain).
createdAt
string
ISO 8601.
updatedAt
string
ISO 8601.
completedAt
string?
ISO 8601.
providerData
ProviderData
Method-specific data (below).
Deposit methods
method
What happened
flow
onramp
A fiat purchase (card, Apple Pay, bank) through the on-ramp.
deposit_with_fiat
smart_wallet
The user sent crypto to their per-user smart wallet (the QR flow), and Swapper swapped it onward.
transfer_crypto
deposit_address
The user sent crypto to a deposit address — shown as a QR code in the widget, or an API deposit address — from any wallet or exchange, and it was swapped and delivered to your destination.
transfer_crypto
dex_swap
The user connected their own wallet and signed the swap route.
wallet_deposit
Both QR settlement paths share flow: "transfer_crypto" — group on flow to count the QR product as one. (The smart_wallet leg of an on-ramp sweep also reports transfer_crypto; link it to its onramp deposit before counting.) Handle unknown method values gracefully: new ones can be added.
Asset
chainId
string
Chain identifier.
tokenAddress
string
Token contract address.
tokenSymbol
string?
Token symbol, when known.
amount
string?
Amount in the token's smallest unit.
amountUsd
string?
USD value, when known.
ProviderData
Discriminated by type:
New fields can be added to any of these objects — ignore fields you don't recognize.
Example — smart-wallet swap
Verifying the signature
When you have a signing secret, every request includes an X-Webhook-Signature header: an HMAC-SHA256 of the raw request body, keyed with your signing secret, Base64-encoded. Verify it before trusting a payload.
Algorithm
HMAC-SHA256
Key
Your signing secret, used as-is (the UTF-8 string from the dashboard — don't decode it)
Payload
The exact bytes of the request body (UTF-8 JSON)
Encoding
Base64
Header
X-Webhook-Signature
No secret, no signature. Until you generate a signing secret in the dashboard, deliveries carry no X-Webhook-Signature header. Once you have one, reject requests without a valid signature.
Rotating the secret. Rotate it in the dashboard (Webhooks → Signing secret). New deliveries are signed with the new secret immediately — there's no overlap period. A retry of an event first sent just before the rotation can still carry the old signature, so accept both secrets for a minute or two after rotating.
Delivery, retries & idempotency
Attempts: each event is delivered up to twice — an initial attempt, then one retry about 30 seconds later if the first doesn't succeed.
Several endpoints: each configured URL gets its own delivery and retry, in parallel — a slow or failing endpoint doesn't hold up the others.
Per-attempt timeout: 10 seconds. A slow response is treated as a failure.
Success = HTTP 2xx. Any non-2xx (or a timeout) triggers the retry; after the second failure we stop, and the event is not redelivered later.
Idempotency: a retry redelivers the same event, so deduplicate on
eventIdand make your handler idempotent. Return200quickly, then process asynchronously.
Linking onramp ↔ smart-wallet deposit
Advanced — only relevant if you support fiat on-ramps that are swapped onward using smart wallets.
When a fiat on-ramp funds one of our smart wallets and we swap those funds onward, you receive two independent deposits — one onramp and one smart_wallet — each as its own transaction.completed event. They are correlated on-chain, by the tx that delivered crypto into the smart wallet:
the onramp deposit carries that delivery tx as
depositTxHash;the smart_wallet deposit carries
fundingTxs— every tx that funded the swap.
A smart_wallet deposit belongs to an onramp deposit when its fundingTxs contains the onramp's depositTxHash:
Event order is not guaranteed — the swap often completes before the on-ramp settles — so buffer an unmatched deposit (keyed by the funding tx) until its partner arrives.
Things to know
Don't double-count volume. The two deposits represent the same money (fiat → token). Count the flow once, keyed by the funding tx.
onrampcompletion depends on destination. A standalone on-ramp (delivered straight to an external wallet) is fully done atcompleted. If it funds a smart wallet, final delivery is the linkedsmart_walletdeposit's event (which may arrive later).destinationAddressdiffers by design: the on-ramp deposit targets the smart wallet (intermediate); the smart_wallet deposit targets the user's final wallet.Field presence:
fundingTxsis only onsmart_walletdeposits;depositTxHashis ononrampdeposits and absent on plaindex_swap.Compare hashes case-insensitively.
Deposit-address deposits (deposit_address) need no linking: each user transfer produces exactly one deposit and one transaction.completed event, describing the source and your configured destination — even when Swapper delivers the funds in two hops internally.
Support
First check Recent deliveries on the dashboard's Webhooks page: it lists every event Swapper sent (time, event type, deposit id, endpoint). It shows what was sent, not how your endpoint responded — check your own logs for that.
If something still looks wrong, open a ticket in Discord with your integratorId, an example eventId, the relevant deposit.id and funding tx hash (depositTxHash or a fundingTxs entry), recent log entries, and your endpoint URL. See Support.
Last updated