Webhooks
Each of the board’s own syncs takes its platform’s webhooks at POST /b/<board>/webhooks/<key>, where <key> is the sync’s key in defineWorkbus. The route needs no bearer token: its provider verifies the platform’s signature instead. A delivery the provider accepts is kept in that sync’s Inbox, a Durable Object, before the platform hears 200, so nothing it was told is lost.
import { defineWorkbus, githubProvider, linearProvider, slackProvider } from 'workbus'
export const { Ledger, Relay, Mailbox, Inbox, Workbus, BoardSession, gateway } = defineWorkbus((env) => ({ sync: { github: githubProvider({ webhookSecret: env.GITHUB_WEBHOOK_SECRET, repos: { 'acme/web': 'eng/web' } }), slack: slackProvider({ signingSecret: env.SLACK_SIGNING_SECRET, channels: { C0123456789: 'support' } }), linear: linearProvider({ webhookSecret: env.LINEAR_WEBHOOK_SECRET, teams: { ENG: 'eng/issues' } }), },}))
export default { fetch: (request, env) => gateway(request, env) }With that Worker under wrangler dev (the bindings of Configuration, and the three secrets in .dev.vars), requests signed as each platform signs them get these answers:
$ node hooks.mjs http://127.0.0.1:18831/b/acmegithub ping, signed 200 ponggithub ping, wrong secret 401 not signed by this appgithub issues.opened, signed 200 kept 1slack url_verification 200 c-123slack, 10 minutes old 401 too old, or no timestamplinear, signed 200 kept 1linear, 2 minutes old 401 too old, or no webhookTimestampa key the deployment has no sync for 404 {"error":{"code":"no_sync","message":"this board has no sync jira"}}hooks.mjs
// Sends webhooks signed as each platform signs them.import { createHmac } from 'node:crypto'const [base] = process.argv.slice(2)const hmac = (key, text) => createHmac('sha256', key).update(text).digest('hex')const send = async (label, path, body, headers) => { const response = await fetch(base + path, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body }) console.log(label.padEnd(38) + response.status + ' ' + (await response.text()).trim())}// GitHub: X-Hub-Signature-256 is sha256= and the HMAC of the body.const ping = JSON.stringify({ zen: 'Keep it logically awesome.' })await send('github ping, signed', '/webhooks/github', ping, { 'x-github-event': 'ping', 'x-github-delivery': 'd-1', 'x-hub-signature-256': 'sha256=' + hmac('gh-test-secret', ping) })await send('github ping, wrong secret', '/webhooks/github', ping, { 'x-github-event': 'ping', 'x-github-delivery': 'd-1', 'x-hub-signature-256': 'sha256=' + hmac('another', ping) })const issue = JSON.stringify({ action: 'opened', repository: { full_name: 'acme/web' }, issue: { number: 12, title: 'Export does nothing', body: 'Clicking export does nothing.', user: { id: 7, login: 'grace' }, labels: [] }, sender: { id: 7, login: 'grace' } })await send('github issues.opened, signed', '/webhooks/github', issue, { 'x-github-event': 'issues', 'x-github-delivery': 'd-2', 'x-hub-signature-256': 'sha256=' + hmac('gh-test-secret', issue) })// Slack: X-Slack-Signature is v0= and the HMAC of v0:<timestamp>:<body>, within 5 minutes.const now = Math.floor(Date.now() / 1000)const challenge = JSON.stringify({ type: 'url_verification', challenge: 'c-123' })await send('slack url_verification', '/webhooks/slack', challenge, { 'x-slack-request-timestamp': String(now), 'x-slack-signature': 'v0=' + hmac('slack-test-secret', 'v0:' + now + ':' + challenge) })await send('slack, 10 minutes old', '/webhooks/slack', challenge, { 'x-slack-request-timestamp': String(now - 600), 'x-slack-signature': 'v0=' + hmac('slack-test-secret', 'v0:' + (now - 600) + ':' + challenge) })// Linear: Linear-Signature is the HMAC of the body; webhookTimestamp within a minute.const comment = JSON.stringify({ action: 'create', type: 'Comment', webhookTimestamp: Date.now(), data: { id: 'c1', body: 'still broken', issueId: 'i1', userId: 'u1' } })await send('linear, signed', '/webhooks/linear', comment, { 'linear-signature': hmac('linear-test-secret', comment) })const old = JSON.stringify({ action: 'create', type: 'Comment', webhookTimestamp: Date.now() - 120000, data: { id: 'c1' } })await send('linear, 2 minutes old', '/webhooks/linear', old, { 'linear-signature': hmac('linear-test-secret', old) })await send('a key the deployment has no sync for', '/webhooks/jira', '{}', {})The signed issue became a thread in eng/web, written by the platform user:
{"id":"2","channel":"eng/web","text":"**Issue #12: Export does nothing**\n\nClicking export does nothing.","thread":"github:acme/web:12:issue","labels":{"issue":"acme/web#12","state":"open"},"by":{"actor":"github:user:7","principal":"github:user:7","profile":null},"from":"github"}What every webhook gets
Section titled “What every webhook gets”| Answer | When |
|---|---|
200, kept <n> |
Verified; n events are durable in the Inbox. |
200, nothing to keep |
Verified, but nothing in it maps to the board (an unmapped repo, channel, or team). |
| 200, the provider’s own body | A handshake: GitHub’s ping, Slack’s url_verification. |
| 401, plain text | The signature doesn’t match, or the delivery is too old. Nothing is kept. |
404 no_sync |
The deployment has no sync with that key. |
501 no_inbox |
The deployment binds no INBOX. |
Each event is kept under the platform’s own delivery ID, so a platform’s retry of the same delivery is kept once. The Inbox imports each platform thread’s events in order, 5 tries each with backoff; an event that fails all 5 is recorded failed and its thread goes on. GET /inbox/<key> shows what it holds, raw payloads included, and POST /inbox/<key>/replay (manage everywhere) gives failed events 5 fresh tries:
$ curl -s "$WORKBUS_URL/inbox/github/replay" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{}'{"replayed":0}GitHub
Section titled “GitHub”POST /b/<board>/webhooks/<key>, usually key github. Point a GitHub App’s webhook (or a repository webhook) at it with content type application/json and the same secret as webhookSecret.
- Verifies
X-Hub-Signature-256:sha256=and the hex HMAC-SHA256 of the raw body underwebhookSecret, compared in constant time. A body that isn’t JSON is refused the same way. - Delivery ID:
X-GitHub-Delivery. - Answers
pingwithpong. - Maps
issuesandpull_request(opened, edited, closed, reopened),issue_comment,pull_request_review(submitted), andpull_request_review_comment, in repositories named inrepos, and, withdocs,pushto the docs branch: one import per Markdown file underdirit added or changed (not the app’s own pushes, bybotUserId). Withprojects,projects_v2_item(any action) for a configured Project, by itsproject_node_id: one import that reads the item through GraphQL. The app’s own changes (bybotUserId) are dropped. An opened issue or pull request starts a thread (unlessstartssays no); comments are replies; edits, deletes, and state changes follow. A thread’s state is itsstatelabel.
POST /b/<board>/webhooks/<key>, usually key slack. Set it as the Slack app’s Events API request URL; Slack checks it with url_verification first.
- Verifies
X-Slack-Signature:v0=and the hex HMAC-SHA256 ofv0:<X-Slack-Request-Timestamp>:<body>undersigningSecret. A timestamp more than 5 minutes from now, either way, is refused as stale. - Delivery ID: the payload’s
event_id. - Answers
url_verificationwith itschallenge, as plain text. - Maps
event_callbackmessages in channels named inchannels: a channel message starts a thread, a thread reply is a reply, and edits, deletes, and reactions follow. The bot’s own messages and reactions wait for the courier’s receipt and are not imported again.
Linear
Section titled “Linear”POST /b/<board>/webhooks/<key>, usually key linear. Create a Linear webhook for Issues and Comments with this URL; its signing secret is webhookSecret.
- Verifies
Linear-Signature: the hex HMAC-SHA256 of the raw body underwebhookSecret. The body’swebhookTimestamp(milliseconds) must be within one minute of now. - Maps
IssueandCommentevents for teams named inteams: a new issue starts a thread, with its identifier, state, and labels as board labels; comments are replies; edits, removals, and state and label changes follow.
Notion
Section titled “Notion”POST /b/<board>/webhooks/<key>, usually key notion. Make a webhook subscription on the integration (API version 2026-03-11) with this URL, for Page content updated, Page properties updated, and Page created. Sync with Notion walks through it.
- Verification: a new subscription’s first request carries
verification_tokenand notype. The board answers it 200 and writes the token to the Worker’s logs, for the subscription’s Verify dialog and forwebhookSecret. UntilwebhookSecretis set, every other delivery is a 401,no webhook secret is set for this sync yet. - Verifies
X-Notion-Signature:sha256=and the hex HMAC-SHA256 of the raw body underwebhookSecret, compared in constant time. Otherwise 401,not signed by this subscription. A body that isn’t JSON is a 400. - Delivery ID: the payload’s
id. - Maps
page.content_updated,page.properties_updated,page.created, andpage.undeleted, for pages named inpages, to one import of that page. Anything else is answered and kept as nothing.
Your own sync
Section titled “Your own sync”A provider is any object with the SyncProvider interface (import type { SyncProvider } from 'workbus'): receive(request, { key }) verifies and normalizes a webhook and answers { events, response? }, where a response (a 401, a challenge) replaces the usual one. import turns each kept event into board imports, and post, edit, delete, react, and startTyping copy board writes back. A provider that keeps docs adds docTarget(path, key), which names the target a doc at that path attaches to (or null), and doc(input, { key, call }), which writes a doc’s whole body to the platform when it is created, edited, or moved. A provider that keeps a synced root’s labels or task adds labels({ targets, root, set, unset }, { key, call }), called when the root’s labels change on the board, and task({ targets, root }, { key, call }), called when its task changes state; root is the root as it is now, with its labels and task. The sync’s own label writes carry its key, so they don’t come back to it. GitHub Projects uses both. Throw SyncRetry to try again later or SyncRefused to record a failure now. The providers in src/sync are working examples.
Verified by
Section titled “Verified by”node --test test/sync/providers.node-test.ts in packages/workbus checks each verification, including stale and wrong-secret deliveries, and the mapping of each platform’s events:
✔ slack: a request signed with the secret, now, is verified (12.75475ms)✔ slack: one signed with another secret, or a changed body, is not (1.736917ms)✔ slack: a signature over a timestamp more than 5 minutes off is stale, either way (0.612209ms)✔ linear: a delivery signed with the secret, sent in the last minute, is verified (0.389917ms)✔ linear: one signed with another secret, or a changed body, is not (0.718542ms)✔ linear: a webhookTimestamp more than a minute off, or none, is stale (0.404917ms)✔ github: its webhook secret can be a Secrets Store binding too (0.677041ms)ℹ tests 13ℹ pass 13ℹ fail 0node --test test/sync/github-docs.node-test.ts test/sync/notion.node-test.ts checks the docs half of GitHub and Notion against stand-ins for their APIs, Notion’s verification included:
✔ a push to another branch, or the app's own, means nothing (1.335791ms)✔ a new subscription is answered, a signed change to a page it keeps is one event, anything else none (14.165417ms)✔ with no webhook secret yet, only the verification request is answered (0.603875ms)ℹ tests 18ℹ pass 18ℹ fail 0