The best way to control Claude Code, Codex and more from any computer or phone
docs(connect): held webhooks are kept per managed link (#23612)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Nov 2, 2026 at 18:32 UTC
371c9a9b75f1afe00b529be470f89c0c0fa07a17
1 file changed
+19
-11
docs/internals/t3-connect.md
+19
-11
@@ -13,22 +13,30 @@ of its traces and leaves token and signature verification to the environment
13
14
By default the forwarder stores nothing. An environment can opt in to having
15
the relay hold requests while it is offline
16
-(`hold_webhooks_while_offline` on its link). Only then does the relay store the
17
-raw request, including the hook token in the path, in a Durable Object for
18
-that environment, with SQLite storage. The object pushes held requests back
19
-through the tunnel from its alarm, oldest first, and backs off while the
20
-environment stays away. When the tunnel reconnects, the environment asks the
21
-relay to deliver right away. Requests are deleted once the environment
22
-answers, after 24 hours, or when no user has the environment linked. The relay
23
-still never checks the token; delivery goes through the same environment route.
16
+(`hold_webhooks_while_offline` on its links). Only then does the relay store the
17
+raw request, including the hook token in the path, in a Durable Object with
18
+SQLite storage. There is one object per managed link, keyed by its endpoint
19
+key: each account that links the environment gets its own held requests,
20
+order, and caps. The object pushes held requests back through the tunnel from
21
+its alarm, oldest first within each hook, and backs off while the environment
22
+stays away. A hook that answers busy is skipped for the rest of that run, so
23
+other hooks on the link can overtake it. When
24
+the tunnel reconnects, the environment asks the relay to deliver right away to
25
+each of its links. Requests are deleted once the environment answers, after 24
26
+hours, when their link is unlinked, or when the environment turns holding off,
27
+which clears every link it proved. Both clears are best effort: unlinking logs a
28
+failed clear and continues, and turning holding off stops at the first link it
29
+cannot clear, so those requests wait for the 24-hour expiry. The relay still
30
+never checks the token;
31
+delivery goes through the same environment route.
32
Every forward carries `x-t3-relay-delivery-id`, so a request that reached the
33
environment before a timeout and is delivered again later runs once
34
([inbox object](../../infra/relay/src/hooks/HookInboxObject.ts)).
35
36
A Durable Object, not Postgres or Queues, because held requests are write-once,
29
-read-once bodies of up to 1 MiB that need per-environment order, caps, and
30
-retry timing. Queues cap messages at 128 KB and cannot hold one environment's
31
-requests back while it is away.
37
+read-once bodies of up to 1 MiB that need per-link order, caps, and retry
38
+timing. Queues cap messages at 128 KB and cannot hold one link's requests back
39
+while its environment is away.
40
41
Clerk, deployment, and native authentication setup live in the
42
[Connect setup runbook](../operations/connect-setup.md).