Webhook delivery

Relay delivers each webhook at least once and keeps its request body and event_id unchanged across retries.

Delivery policy

Setting	Value
Initial delivery	1 immediate attempt
Retries	Up to 10
Response window	10 seconds per attempt
Backoff	Exponential from 2 seconds to a 10-minute cap
Total failed attempts	11
Duplicate delivery	Possible

The nominal retry delays are 2s, 4s, 8s, 16s, 32s, 64s, 128s, 256s, 512s, and 600s.

Retry classes

Result	Relay action
HTTP `2xx`	Succeed
HTTP `429`	Retry
HTTP `5xx`	Retry
Response timeout	Retry
Temporary connection or network failure	Retry
Invalid URL, permanent DNS failure, or unsafe destination	Terminal
HTTP `3xx`	Terminal, redirect is not followed
Any other HTTP response	Terminal

Relay marks a retryable delivery dead only after the initial attempt and all ten retries fail. A terminal response stops earlier. Relay resolves the destination for each attempt. It rejects localhost, private, link-local, and cloud metadata addresses before sending.

Receiver pattern

verify signature
  → insert event_id if absent
  → commit durable inbox
  → return 2xx
  → process asynchronously

If the backend commits but the response is lost, Relay retries with the same event_id. Store that ID under a uniqueness rule and return success for a duplicate without repeating model work, tools, or replies.

Delivered meaning

For message.received, Relay marks the agent recipient Delivered only after the receiver returns 2xx. The receiver contract requires a durable commit before that response.

Terminal state and redrive

Relay stores every attempt and terminal result in PostgreSQL. Succeeded, dead, and path-transferred rows remain for 30 days, then Relay prunes them. PostHog receives derived analytics only. It is never the delivery system of record. An operator can redrive a dead webhook from Relay Console for 72 hours after the event was created. Redrive restarts the delivery attempts with the same frozen body and event_id. After 72 hours, recover current Chat and Message state through ordinary REST reads.

Review with an agent

Audit a webhook receiver for retries and durable deduplication. Copy this prompt into your coding agent.

You are auditing a codebase that receives Relay webhooks.

This is read-only. Do not change code unless I ask.

Read https://docs.relayapp.im/llms.txt, the Webhook guides, and the current Relay OpenAPI.
Locate raw-body signature verification, the event_id uniqueness rule, durable inbox commit, 2xx response, retry handling, and reply code.
Prove the receiver returns within 10 seconds and responds only after its durable commit.
Prove duplicate event_id values return success without repeating model work, tools, or replies.
Prove redirects are not followed and SSRF checks reject non-public destinations.
Prove ordinary 4xx responses are used only for terminal requests.
Prove recovery uses ordinary REST reads and the documented Console redrive window.
Report Check | Status | file:line evidence | Fix.
Mark anything you cannot prove as unknown.

Introduction

Getting started

Messaging

Chats

Contacts

Agent events

Webhooks

WebSocket

Platform

Examples

Delivery policy

Retry classes

Receiver pattern

Delivered meaning

Terminal state and redrive

Review with an agent

​Delivery policy

​Retry classes

​Receiver pattern

​Delivered meaning

​Terminal state and redrive

​Review with an agent

​Related

Delivery policy

Retry classes

Receiver pattern

Delivered meaning

Terminal state and redrive

Review with an agent

Related