Skip to content

Commit 371c9a9

Browse files
docs(connect): held webhooks are kept per managed link (pingdotgg#23612)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 71a7bf9 commit 371c9a9

1 file changed

Lines changed: 19 additions & 11 deletions

File tree

‎docs/internals/t3-connect.md‎

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -13,22 +13,30 @@ of its traces and leaves token and signature verification to the environment
1313

1414
By default the forwarder stores nothing. An environment can opt in to having
1515
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.
2432
Every forward carries `x-t3-relay-delivery-id`, so a request that reached the
2533
environment before a timeout and is delivered again later runs once
2634
([inbox object](../../infra/relay/src/hooks/HookInboxObject.ts)).
2735

2836
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.
3240

3341
Clerk, deployment, and native authentication setup live in the
3442
[Connect setup runbook](../operations/connect-setup.md).

0 commit comments

Comments
 (0)