A webhook makes oak.space send an HTTP POST to a URL of yours when something happens in a repo — to notify a chat channel, kick off an external build, or update a dashboard.
Events#
| Event | Fires when |
|---|---|
branch.created | A branch is pushed for the first time. |
push | An existing branch gets new commits (including a revert). |
merge | A branch is squash-merged onto main. |
branch.closed | A branch is closed without merging. |
branch.reopened | A closed branch is reopened. |
branch.approved | Someone approves a directory's changes on a branch. Approving several boundaries at once sends one event each. |
mark.moved | A mark is created, moved forward or rolled back. commit is where it points now. |
Add a webhook#
Under the repo's Settings → Webhooks (you need write access), enter:
- the URL to deliver to — it must resolve to a public address;
- a secret, to sign deliveries (recommended);
- which events to send. Choosing none means all of them, including events added later, so switch on
eventand ignore what you don't handle.
Or over the API:
curl -X POST https://oak.space/api/acme/web/webhooks \
-H "Authorization: Bearer $OAK_API_KEY" -H "Content-Type: application/json" \
-d '{"url": "https://ci.example.com/oak", "secret": "s3cret", "events": ["push", "branch.created"]}'
Leave events out (or empty) to get every event. Names Oak doesn't send are dropped, and a list naming none it sends is refused with a 400 that lists them, so a typo never subscribes you to everything.
List them with GET /api/{owner}/{name}/webhooks and remove one with DELETE /api/{owner}/{name}/webhooks/{id}.
Who reads it#
A webhook only sends what the people reading it can see. Oak can't know who reads the channel or endpoint, so by default that's anyone who can read the repo. When a path rule hides a folder from some readers, a branch that touches that folder, and its merge to main, are left out.
If a webhook posts somewhere only one group reads, such as your team's own channel, set Who reads it to that group. It then sends everything that group can see. Only a member of the group, or an owner or admin of the organization, can choose it. Over the API, pass "audience": "<group>" when you create a webhook, or change it later:
curl -X PATCH https://oak.space/api/acme/web/webhooks/12 \
-H "Authorization: Bearer $OAK_API_KEY" -H "Content-Type: application/json" \
-d '{"audience": "internal"}'
Send "audience": null to go back to every reader. Deleting the group does the same.
Payload#
Each delivery is a JSON POST:
POST /oak HTTP/1.1
Content-Type: application/json
User-Agent: oak-webhooks/1
X-Oak-Event: push
X-Oak-Delivery-Id: 7f3c…
X-Oak-Signature-256: sha256=5d61…
{
"event": "push",
"owner": "acme",
"repo": "web",
"branch": "fix-login-redirect",
"commit": "8fcf5aed1b2c…",
"pusher": "zdgeier",
"timestamp": "2026-10-06T17:04:11.512Z"
}
| Field | Value |
|---|---|
event | The event name, from the table above. |
owner, repo | The repository. |
branch | The branch the event is about. |
commit | The commit it's about — for merge, the new squash commit on main. |
pusher | Who did it. |
timestamp | When the delivery was sent (RFC 3339, UTC). |
mark, move_id, move_kind, from_commit | On mark.moved: the mark, the move, create, forward or rollback, and where it was before. |
boundary | The approved boundary's path (a directory or file), on branch.approved ("" is the whole repo). |
description | The start of the branch's description, up to 500 characters, when the branch has one. |
url | The page for the branch, when the event has one. |
Fields that don't apply are left out rather than sent as null. X-Oak-Delivery-Id, when present, is unique per delivery — use it to ignore duplicates.
Verify the signature#
When a webhook has a secret, X-Oak-Signature-256 is sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with the secret. Compute it over the bytes exactly as received, before parsing the JSON, and compare in constant time:
import hmac, hashlib
def verify(secret: str, body: bytes, header: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header or "")
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(secret, rawBody, header = "") {
const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
return expected.length === header.length && timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}
Discord#
Paste a Discord channel webhook URL (https://discord.com/api/webhooks/…) and Oak recognizes it: instead of the JSON payload, it posts a readable message to the channel. No secret is needed, and no signature is sent.
Slack#
Paste a Slack incoming webhook URL (https://hooks.slack.com/services/…) and Oak recognizes it the same way: the channel gets a readable message with a link to the branch, and the start of the branch's description. Create the URL by adding an incoming webhook to a Slack app in your workspace. No secret is needed, and no signature is sent.
Delivery#
- Deliveries are sent shortly after the event and retried with backoff if your endpoint fails, so the same
X-Oak-Delivery-Idcan arrive more than once. - Events can arrive out of order.
- Oak checks that the URL resolves to a public address both when you add it and again before every delivery, and skips it otherwise — so a webhook can't be pointed at internal networks.
- Respond quickly with any
2xx; do slow work after responding.
Using webhooks for external CI#
A webhook is how you'd drive an external CI system: listen for push and branch.created, then fetch that commit with an API key — oak clone acme/web --branch <branch>. To record what passed, have it file a report on the commit (oak report) or move a mark.