Webhooks

Get an HTTP callback on pushes, merges, mark moves and more — signed, or posted to Discord or Slack.

Markdown

All pages

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#

EventFires when
branch.createdA branch is pushed for the first time.
pushAn existing branch gets new commits (including a revert).
mergeA branch is squash-merged onto main.
branch.closedA branch is closed without merging.
branch.reopenedA closed branch is reopened.
branch.approvedSomeone approves a directory's changes on a branch. Approving several boundaries at once sends one event each.
mark.movedA 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:

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"
}
FieldValue
eventThe event name, from the table above.
owner, repoThe repository.
branchThe branch the event is about.
commitThe commit it's about — for merge, the new squash commit on main.
pusherWho did it.
timestampWhen the delivery was sent (RFC 3339, UTC).
mark, move_id, move_kind, from_commitOn mark.moved: the mark, the move, create, forward or rollback, and where it was before.
boundaryThe approved boundary's path (a directory or file), on branch.approved ("" is the whole repo).
descriptionThe start of the branch's description, up to 500 characters, when the branch has one.
urlThe 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#

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.

Something here wrong or missing? Run oak feedback -m "…" or email [email protected].