Webhooks

​

Configure an endpoint

1. Open the Partner Dashboard.
2. Select the organization and app.
3. Open Webhooks, add the endpoint URL, and create the webhook.
4. Copy the webhook secret and store it in your server’s secret manager.

​

Verify every request

​

Payload shape

{
  "swap": {
    "id": "SWAP_ID",
    "status": "ls_transfer_pending",
    "destination_address": "0x...",
    "requested_amount": 100,
    "fail_reason": null,
    "metadata": {
      "reference_id": "your-external-id"
    },
    "transactions": []
  },
  "quote": {
    "receive_amount": 99.5,
    "min_receive_amount": 99.0
  },
  "deposit_actions": []
}

​

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.