Wallet Webhooks Setup
Setup
Configure where deposit and withdrawal events get delivered.
Wallet webhooks attach at two granularities: at the wallet level (every transaction on every address) or per individual address (overrides the wallet URL for that one address). Both can be set at creation time or updated later.
Wallet-level routes
Deliveries cover every address on the walletPOST/merchant/wallets
Attach at wallet creation
Include webhookUrl in the create-wallet request body. Every transaction on the wallet — at any address — will be delivered here.
PUT/merchant/wallets/:id/webhook
Update an existing wallet
Replace or remove the wallet-level webhook URL after creation. Useful when migrating endpoints or rotating to a new ingest service.
Per-address routes
Override the wallet URL for a single addressPOST/merchant/wallets/:id/addresses
Attach at address creation
Include webhookUrl when minting a new deposit address. Overrides the wallet-level URL just for transactions on this address — ideal for per-customer attribution.
PUT/merchant/wallets/:id/addresses/:aId/webhook
Update an existing address
Change or remove the per-address webhook URL after creation. The wallet-level URL keeps applying to any address without its own override.
Wallet vs per-address — which to use
Attach at the wallet level when one endpoint handles every event for that wallet's currency. Attach at the address level when different customers, invoices, or accounting buckets should notify different downstream services. Per-address URLs take precedence when both are set.
HTTPS endpoints only
The URL you supply must be publicly reachable over HTTPS. Verify the HMAC signature on every delivery — never trust payload contents until the signature checks out. See Authenticating Requests.
Where to next?
Pick the most useful next step.