Skip to main content
Instead of polling for status updates, you can configure webhooks to receive real-time notifications when swap or on-ramp order statuses change.

Setting Up Webhooks

1

Create a Webhook Endpoint

Set up an HTTPS endpoint on your server to receive webhook payloads.
2

Register the Webhook

Use the Partner API to register your webhook URL.
3

Verify Signatures

Validate incoming webhook signatures to ensure authenticity.
4

Process Events

Handle the webhook payload and update your application state.

Registering a Webhook

Webhook Events

Webhook Payload

Each webhook delivery includes a JSON payload with the event details:

Signature Verification

Every webhook request includes a X-Hypermid-Signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook secret.
Always verify the webhook signature before processing the payload. Never trust incoming webhooks without signature validation, as anyone could send requests to your endpoint.

Managing Webhooks

List Webhooks

Delete a Webhook

Best Practices

  1. Respond quickly — Return a 200 status within 5 seconds. Process the event asynchronously if needed.
  2. Handle duplicates — Webhooks may be delivered more than once. Use the transactionId or orderUid to deduplicate.
  3. Use HTTPS — Webhook URLs must use HTTPS for security.
  4. Implement retry logic — If your endpoint returns a non-2xx status, Hypermid will retry the delivery with exponential backoff.
  5. Log everything — Store the raw webhook payload for debugging purposes.
  6. Keep your secret safe — Store the webhook signing secret securely and rotate it periodically.