Webhooks

Building applications at scale requires integrating with Relay’s system at instant speed. Rather than polling the API for status updates, webhooks push transaction lifecycle events directly to your server the moment they happen. Configure a webhook endpoint and Relay will notify your backend in real time as quotes are processed — lightweight, no polling, low latency.

Configuring a Webhook

Webhooks are self-serve in the Relay Dashboard. Each App can have one webhook endpoint. Relay posts events to this endpoint for requests made with any API key in the App. To configure one:

Sign in to the Relay Dashboard.
Open Apps and select the App you want to configure.
Open the Advanced tab. In the Webhooks section, click Configure.
Enable the webhook and enter your Webhook URL — an HTTPS endpoint to POST to when the status of a request changes (e.g. https://my.server/receive-relay-event).
Optionally add Custom Headers to include on every webhook request (e.g. Authorization: Bearer 0x123), then save.

Webhook Events

Relay Webhooks specifically stream transaction statuses for both cross and same-chain status, though the stages differ slightly.

status	indication
waiting	waiting for origin chain deposit
depositing	origin deposit confirmed via /execute API, fill pending
pending	origin chain deposit confirmed, fill pending submission
submitted	fill submitted on destination chain
success	fill succeeded
failure	fill failed
refund	refunded

Only success and refund are final. A failure can still move back to pending on a retry or on to refund, so do not treat it as the last event for a request. See Get Status for the full lifecycle.

Example Payload

{
  "event": "request.status.updated",
  "timestamp": 1774993296140,
  "data": {
    "status": "refund",
    "inTxHashes": [
      "0x..."
    ],
    "txHashes": [],
    "updatedAt": 1774993296121,
    "originChainId": 8453,
    "destinationChainId": 42161,
    "depositAddress": {
      "address": "0x..",
      "depositAddressType": "open", // open / strict
      "depositor": "0x..", //nullable
      "depositTxHash": "0x..", //nullable — origin-chain tx hash of the depositor's transfer into the deposit address
    }, //nullable
    "requestId": "0x...",
    "referrer": "your-referrer", //nullable — echoes the referrer supplied on the originating quote request
    "details": null,
    "failReason": "DOUBLE_SPEND",
    "refundFailReason": "N/A"
  }
}

The referrer field echoes the value supplied on the originating quote request, or null if no referrer was provided. Use it to attribute webhook events back to the request source (campaign, partner, or integration surface) without an extra lookup. The details, failReason, and refundFailReason fields mirror the same fields returned by GET /intents/status/v3:

Field	Description
`details`	Additional status context (e.g. decoded revert data on failures). `null` when no extra detail is available.
`failReason`	Reason a fill failed. Returns `"N/A"` on non-failure statuses. On `failure`, `fallback`, and `refund` statuses, returns the recorded reason or `"UNKNOWN"` when no specific reason is available. See `/intents/status/v3` for the enum.
`refundFailReason`	Reason a refund leg failed. Defaults to `"N/A"` when no refund-leg failure is recorded. See `/intents/status/v3` for the enum.

For deposit-address requests, events are sent under the requestId that owns the fill. If Relay regenerates the quote, events carry the new requestId and nothing is sent for the quote-time one. Match these events to your order with depositAddress.address, and to the funding transfer with depositAddress.depositTxHash. See Tracking Transactions. By default we post all status updates. If you’re only interested in certain statuses you can filter on the status property in your endpoint.

Verification

Each webhook request includes two headers for verification:

Header	Description
`X-Signature-Timestamp`	Unix timestamp of when the webhook was sent
`X-Signature-SHA256`	HMAC-SHA256 signature of the request

Relay signs each event with the API key used for the request. To verify a webhook is authentic, compute the HMAC-SHA256 hash of ${timestamp}.${body} using that API key as the secret, and compare it to the X-Signature-SHA256 header value. The App’s webhook receives events for requests made with any active key in the App. Check the signature against each of these keys. During a key rotation, that means both the old and the new key. Relay stops sending events for a key’s requests once you deactivate it, including requests that are still in progress.

Example Verification

import crypto from 'crypto';

function verifyWebhook(req, apiKeys) {
  const timestamp = req.headers['x-signature-timestamp'];
  const signature = req.headers['x-signature-sha256'];
  const body = JSON.stringify(req.body);
  const signatureBuffer = Buffer.from(signature, 'hex');

  return apiKeys.some((apiKey) => {
    const expectedBuffer = crypto
      .createHmac('sha256', apiKey)
      .update(`${timestamp}.${body}`)
      .digest();

    return (
      signatureBuffer.length === expectedBuffer.length &&
      crypto.timingSafeEqual(signatureBuffer, expectedBuffer)
    );
  });
}

Requests that fail verification should be rejected with a non-2xx status code.

Webhook Delivery & Reliability

Relay’s built-in webhook service includes up to 10 retries with exponential backoff. For most integrations, this is sufficient. For production deployments requiring guaranteed delivery, routing, fan-out, or detailed observability, we recommend using a webhook gateway like Hookdeck. A gateway sits between Relay and your server, giving you:

Guaranteed delivery with configurable retry policies
Routing & fan-out to multiple destinations from a single source
Event inspection & replay for debugging
Rate limiting to match your server’s capacity

To set this up, use your Hookdeck ingestion URL as the Relay webhook endpoint and route events to your server from there. See Hookdeck’s getting started guide for setup instructions.

API Reference

Websockets

Configuring a Webhook

Webhook Events

Example Payload

Verification

Webhook Delivery & Reliability

​Configuring a Webhook

​Webhook Events

​Example Payload

​Verification

​Webhook Delivery & Reliability

Configuring a Webhook

Webhook Events

Example Payload

Verification

Webhook Delivery & Reliability