Skip to main content
Receive Relay events at your HTTPS endpoint in three steps: verify the signature, commit the event, and answer 2xx.

Before you start

  • Create a subscription for the events you need.
  • Load its signing secret as RELAY_WEBHOOK_SECRET in your backend.
  • Give your inbox a unique constraint on event_id, and a worker that reads from it.

Receive and acknowledge

Commit the event before you return 2xx. Mount this handler on the POST route your subscription targets. acceptOnce is your own database write; it resolves after inserting the event, or after finding the same ID already committed:
TypeScript SDK
The SDK verifies the raw body before it parses anything. Your worker then reads the inbox, runs the model or tools, and sends any reply. A duplicate returns the existing row, so the same work never runs twice.

When it fails

Answer 401 when verification fails and store nothing; Relay treats it as terminal and stops retrying. Answer 503 when your inbox is down, and Relay retries with backoff for up to 10 attempts. If your success response never reached Relay, the same event arrives again and your unique constraint absorbs it; read delivery and retries for the full policy.

Next steps