Skip to content

Sync: Inbox and courier

A board’s own sync runs in two satellites per sync key. The Inbox takes the platform’s webhooks and keeps them before it answers; the courier copies what’s written on the board back to the platform, and records a receipt for every copy. A deployment declares its syncs, and gets both:

src/worker.ts
import { defineWorkbus, slackProvider } from 'workbus'
export const { Ledger, Relay, Mailbox, Inbox, Workbus, BoardSession, gateway } = defineWorkbus<Env>((env) => ({
sync: {
// Slack's webhooks at /b/<board>/webhooks/slack; what's written in those threads goes back as the bot.
slack: slackProvider({
signingSecret: env.SLACK_SIGNING_SECRET,
botToken: env.SLACK_BOT_TOKEN,
channels: { [env.SLACK_CHANNEL]: 'support' },
botUserId: env.SLACK_BOT_USER_ID,
}),
},
}))
Sync: Inbox and courierInbound: a GitHub, Slack, Linear, or Notion webhook reaches the Gateway at the sync key's webhook route, where the provider verifies it. The Inbox Durable Object keeps it under its platform event ID, and only then does the platform get 200. The Inbox imports events through the Ledger as the sync, one platform thread at a time, oldest first. Outbound: a write in a synced thread commits in the Ledger, which matches it to the sync's subscription after the commit. The courier, a Mailbox, posts it to the platform as the app, in thread order, retrying a post until it lands, and records a receipt on the board.In: a platform eventPlatforma webhook fromGitHub, Slack,Linear, or NotionGateway/webhooks/<key>the providerverifies itInboxkept under itsplatform event IDretries do nothingLedgerimported asworkbus:sync:<key>thread by thread,oldest first200, once it is keptOut: a board writeWritea reply, edit, orreaction in asynced threadLedgermatches@sync:<key>after the commitCouriera Mailbox, inthread orderposts retry untilthey landPlatformthe copy, postedas the appreceipt: where the copy is
In, an event is kept before the platform hears 200, then imported in order. Out, the courier posts the copy and records a receipt: a copy that exists is never posted again, and the platform's echo is not imported.

Each platform is a SyncProvider (sync/provider.ts): githubProvider, slackProvider, and linearProvider. It verifies and normalizes what comes in (receive), says what each event means as board writes (import), and posts, edits, deletes, reacts, and shows typing on the platform. The Inbox and the courier are the same for all three. Credentials are a Worker secret or a Secrets Store binding, read through one accessor.

An Inbox is a SQLite Durable Object per board and sync key, inbox:<board>:<key> (sync/inbox.ts).

  1. Verify. The platform’s webhook reaches /b/<board>/webhooks/<key>. The provider checks it: GitHub’s x-hub-signature-256, Slack’s signature and its 5-minute window, Linear’s signature. A forged or stale request is a 401 and keeps nothing.
  2. Keep, then answer. The provider turns the request into events, each with the platform’s own ID for it. The Inbox inserts each one it hasn’t seen, by that ID, and only once they’re durable does the Gateway answer 200. A platform that retries a delivery gets the same IDs, and the Inbox does nothing.
  3. Import in order. The Inbox’s alarm imports events through the Ledger as workbus:sync:<key>, one platform thread at a time, oldest first, 8 threads at once. An import’s client ID is derived from the platform’s message, so an import that runs twice lands once.
  4. Retry, then go on. An import that fails is tried again 1 second later, doubling, 5 times in all. Then the event is recorded as failed and its thread goes on.

Raw payloads stay in the Inbox for 7 days and never reach the board log. POST /b/<board>/inbox/<key>/replay gives failed events 5 fresh tries: during one deploy’s rollout, a Ledger still on the old code refused a GitHub event, and replaying it after the rollout made its thread.

The courier is a subscription matched like a watcher, @sync:<key>, delivered by its own Mailbox with a { kind: 'sync', key } sink (sync/courier.ts). The Ledger matches it in its post-commit dispatch, from its outbox cursor, so a write in a synced thread costs nothing extra in its transaction.

For a message.posted in a synced thread, for each of the thread’s targets under that key:

  1. Look for a receipt. If the message already has a copy on that target, it’s done. This is the retry guard: a Mailbox retry after a post that worked never posts it again.
  2. Skip what stays. An import from this same sync (its echo), a noSync message, and a deleted one aren’t copied.
  3. Post, then record. The provider posts it, as the app or bot, and the courier records the copy as a receipt on the board: where the message is on the platform.
  4. Fail visibly. On the Mailbox’s last try, what didn’t go is recorded with message.sync_failed, which shows under the message as undelivered, and the thread goes on.

A reply in a thread that started on the board as a channel target goes in the platform thread its root started there, posting the root first if it hasn’t gone yet. Edits, deletes, and reactions of a copied message are best effort: one try, logged when it fails. Labels aren’t copied out, and a board reply by a person is posted as the app, without naming its author.

A provider that keeps docs names, for a doc’s path, the target its thread attaches to (docTarget). A doc created in or moved into such a path is attached in the same write, and from then on its thread syncs as the doc: the courier hands the provider the doc’s whole body, as it is now, when it is created, edited, or moved (doc), and its comments don’t go out as messages. The provider writes nothing when the platform’s copy already says it, which is the retry guard.

Coming in, a platform’s changed copy is a merge, not an overwrite (sync/docfiles.ts): a whole-body editDoc with merge: true against what the copy was before, so what the board wrote meanwhile stays. When both sides changed a section, the board keeps its text and a task in the doc’s channel says where the other is. An imported merge can hold what the platform’s copy lacks, so it goes back out like any edit. A two-way Notion page is reconciled on every change from either side, against the revision Notion last held (its notion.synced label). A mirror is made with mirror: true, which only a sync may send, and only that sync’s imports change it.

A platform tells the board about the courier’s own post: Slack and GitHub send it back as a new event. The provider marks an event from its own bot user as own, and the import asks the board for that message’s receipt:

  • The receipt is there: the echo is the board’s own copy, and imports as nothing.
  • No receipt yet: the echo beat the courier’s receipt, so the import throws a retry and the Inbox tries again a second later, by which time it’s there.
  • The echo imported first: the receipt answers already_synced, and the courier takes that as done. The message is on the board and on the platform once.

The support channel example under wrangler dev, against a stand-in for Slack’s Web API. Slack’s delivery is sent twice; the triage agent answers on the board; the courier posts it to Slack; and the stand-in sends Slack’s echo back:

$ node try-it.mjs
webhook 200 kept 1
retried 200 kept 1
board thread #2 {"area":"billing","urgency":"high"}, 1 reply by workbus:watch:triage
to slack C0SUPPORT thread 1795216784.000100: Sorry to hear that you were charged twice for November. Can you please provide me with your account information or order number so I can look into this further?

GET /b/desk/inbox/slack shows two events, the question and the echo, each imported once on its first try:

Event ID State Tries What the provider read
Ev1795216786.000200:0 done 1 a reply, own: the bot’s echo
EvQUESTION1795216784.000100:0 done 1 a root: Ada’s question

The thread still has one reply: the echo landed as nothing. The same path ran live against GitHub, a real Slack workspace, and a real Linear workspace; Status lists what each run covered.