Best practices - Relay

Check these nine boundaries before you put your agent backend in front of people.

Review each boundary

Each row is a rule the owning page explains in full. The pattern behind all of them is the same: commit before you acknowledge, retry with the same key, and keep credentials where only your server can read them.

Check	Owning guide
Keep the token in server-side secret storage	Authentication
Verify the raw webhook request before accepting it	Signature verification
Commit and deduplicate events before acknowledging	Webhook delivery or WebSocket ACKs
Run model and tool work after acknowledgment	Webhook delivery
Retry a message with its original key and body	Idempotency
Complete recovery before resuming WebSocket ACKs	FULL sync
Keep event acknowledgment apart from Delivered and Read	Delivery receipts
Store attachment IDs rather than expiring download URLs	Download attachments
Cache only history this contact can access	Message history

When it fails

The failures these rules prevent look alike from the outside: a reply sent twice, a reply never sent, or a message that arrived while your backend was down. Start from the identifiers on the debugging page. The event_id tells you whether an event was delivered twice, and the trace_id matches a request to Relay’s own record of it.

Next steps