# Webhooks

> The webhook route each sync provider serves, and what it verifies.

Source: https://docs.workbus.dev/reference/webhooks/
Markdown: https://docs.workbus.dev/reference/webhooks/index.md
All docs for agents: https://docs.workbus.dev/llms.txt

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`](/reference/configuration/#sync). 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

```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](/reference/configuration/#bindings), and the three secrets in `.dev.vars`), requests signed as each platform signs them get these answers:

```plaintext
$ 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

```js
// 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:

```json
{"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

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

```plaintext
$ curl -s "$WORKBUS_URL/inbox/github/replay" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{}'
{"replayed":0}
```

## 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 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.

## Slack

`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.

## 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 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.

## 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](/guides/sync-notion/#set-it-up) 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.

## 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`](https://github.com/workbus-dev/workbus/tree/main/packages/workbus/src/sync) are working examples.

## 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:

```plaintext
✔ 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:

```plaintext
✔ 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
```
