Events

Webhooks

Signed HTTPS POSTs for landings, refusals, branches, tags, checks, changes and releases, delivered in order and at least once.

Add a webhook#

In the repository's Settings → Webhooks, or over the API:

Shell
curl -X POST https://api.yonedarepo.com/api/v1/repos/<id>/hooks \
  -H "Authorization: Bearer $YONEDA_TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/yoneda", "events": ["land", "change"]}'

The answer holds the signing secret (whsec_…). It is shown once. The URL must be a public https:// address. Managing webhooks needs the owner or a token with repo:admin. A repository holds up to 20 webhooks.

Events#

EventSent when
landA commit landed on a branch
mergedA landing was merged on the server with concurrent work
refusedA landing was refused
branchA branch was created, moved or deleted
tagA tag was created
checkA check concluded: pass, fail or error
changeA Landing (a change request) was opened, commented, landed, closed or deleted (change.opened, change.commented, change.landed, change.closed, change.deleted)
releaseA release was published or deleted (release.published, release.deleted)
repoThe repository was deleted (repo.deleted, sent once). Where deleted repositories can be restored for a time, its purge_at says when that ends at the latest (its owner can end it sooner), and repo.purged is sent once when it is gone for good; a restored repository gets neither. Nothing is delivered after the last of them. The owner resuming automation sends repo.resumed.

Leave out events to get them all. One more name, change.auto, is never included by default: with change, it also delivers change.opened for a Landing a push opened (automatic Landings). Those arrive per branch, and a hook 1,000 payloads behind is switched off. Claiming one with yoneda change create tells every change hook, as opening a Landing does. paths limits the commit messages a hook sees to commits inside those paths; change titles and comment text go only to hooks without paths.

Deliveries#

Each delivery is a POST with a JSON body and these headers:

HeaderValue
X-Yoneda-EventThe event, such as land or change.opened
X-Yoneda-DeliveryA delivery id; the same event retried keeps it
X-Yoneda-Signaturesha256= and the hex HMAC-SHA256 of the raw body, keyed with the secret
  • Events are delivered in the order of the repository's log, at least once: handle a repeated delivery id as a duplicate.
  • Your endpoint has 10 seconds to answer with a 2xx status.
  • Failures are retried with backoff from 10 seconds up to 15 minutes. After 50 failures in a row the hook is switched off.

Verify the signature#

TypeScript
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verified(rawBody: string, header: string, secret: string): boolean {
  const expected = `sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`;
  return header.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Compute the HMAC over the raw request body, before parsing it.

Inspect and delete#

ActionAPIMCP
List webhooks (secrets never shown)GET /repos/<id>/hooksgit_hook_list
The last 50 delivery attemptsGET /repos/<id>/hooks/<hook>/deliveriesgit_hook_deliveries
Delete a webhook (undelivered events are dropped)DELETE /repos/<id>/hooks/<hook>git_hook_delete