Skip to content

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.

worker.js
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/acme
github ping, signed 200 pong
github ping, wrong secret 401 not signed by this app
github issues.opened, signed 200 kept 1
slack url_verification 200 c-123
slack, 10 minutes old 401 too old, or no timestamp
linear, signed 200 kept 1
linear, 2 minutes old 401 too old, or no webhookTimestamp
a key the deployment has no sync for 404 {"error":{"code":"no_sync","message":"this board has no sync jira"}}
hooks.mjs
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"}
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}

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 under webhookSecret, compared in constant time. A body that isn’t JSON is refused the same way.
  • Delivery ID: X-GitHub-Delivery.
  • Answers ping with pong.
  • Maps issues and pull_request (opened, edited, closed, reopened), issue_comment, pull_request_review (submitted), and pull_request_review_comment, in repositories named in repos, and, with docs, push to the docs branch: one import per Markdown file under dir it added or changed (not the app’s own pushes, by botUserId). With projects, projects_v2_item (any action) for a configured Project, by its project_node_id: one import that reads the item through GraphQL. The app’s own changes (by botUserId) are dropped. An opened issue or pull request starts a thread (unless starts says no); comments are replies; edits, deletes, and state changes follow. A thread’s state is its state label.

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 of v0:<X-Slack-Request-Timestamp>:<body> under signingSecret. A timestamp more than 5 minutes from now, either way, is refused as stale.
  • Delivery ID: the payload’s event_id.
  • Answers url_verification with its challenge, as plain text.
  • Maps event_callback messages in channels named in channels: 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.

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 under webhookSecret. The body’s webhookTimestamp (milliseconds) must be within one minute of now.
  • Maps Issue and Comment events for teams named in teams: 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.

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_token and no type. The board answers it 200 and writes the token to the Worker’s logs, for the subscription’s Verify dialog and for webhookSecret. Until webhookSecret is 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 under webhookSecret, 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, and page.undeleted, for pages named in pages, to one import of that page. Anything else is answered and kept as nothing.

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.

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 0

node --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