Configure an endpoint
- Open the Partner Dashboard.
- Select the organization and app.
- Open Webhooks, add the endpoint URL, and create the webhook.
- Copy the webhook secret and store it in your server’s secret manager.
Verify every request
Layerswap uses Svix for webhook delivery. Verify the raw request body and Svix signature headers with the app’s webhook secret before parsing or acting on the payload. Follow the Svix payload verification guide for your server framework. Reject invalid signatures and keep verification ahead of any balance credit, order fulfillment, or database state transition.Payload shape
Layerswap sends swap updates through the Svixpartner event type. The JSON body is a flat object containing the swap ID, status, route, reference, and transactions. For example:
id is the swap ID, reference_id is your app’s correlation reference, and timestamp is the webhook message creation time in Unix milliseconds. Transaction entries include transaction_id, type, from, to, amount, usd_price, usd_value, created_date, timestamp, confirmations, max_confirmations, and explorer_url.
source_address can be null.
Webhook status values use PascalCase: PendingDeposit, PendingWithdrawal, Completed, Failed, Expired, PendingRefund, and Refunded. API swap responses use snake_case values; for example, webhook PendingDeposit corresponds to API user_transfer_pending, and PendingWithdrawal corresponds to ls_transfer_pending. See the status mapping.
Use the swap ID as the durable key, and fetch GET /swaps/{id} before crediting funds or fulfilling an order. Apply business actions using the current swap status, and make repeated processing safe.
Receiver checklist
- Read the raw body before JSON middleware changes it.
- Verify the Svix signature and reject stale or invalid requests according to the verification library.
- Deduplicate side effects by swap ID and resulting status or transaction hash.
- Return a success response only after the event is durably accepted.
- Process asynchronously when downstream work can exceed the request timeout.
- Reconcile periodically with Track swaps.