Webhook event schema

When a wave waits, is refused or fails, its apply job posts one event to notify.webhook, provided notify.webhook_key is set. Send events to your own webhook sets it up and verifies it. Slack and Teams notices need none of it; it is for a program of yours, such as a relay that turns a chat click into terragucci approve --plan.

{
  "schema": "terragucci.notify/v1",
  "id": "4b0c9e...",
  "event": "waiting",
  "sent_at": "2026-10-08T14:02:15.000Z",
  "project": "github.com/acme/infra",
  "forge": "github",
  "repo": "acme/infra",
  "sha": "9d1f0c...",
  "wave": 2,
  "roots": ["envs/prod/app", "envs/prod/db"],
  "run_url": "https://github.com/acme/infra/actions/runs/42",
  "outcome": {
    "schema": "terragucci.outcome/v1",
    "status": "waiting",
    "exit": 3,
    "wave": 2,
    "roots": ["envs/prod/app", "envs/prod/db"],
    "set_digest": "jcs1-sha256:9f2c...",
    "approval_mode": "ledger",
    "approve_command": "terragucci approve wave-2 --plan jcs1-sha256:9f2c..."
  }
}

Headers

Header	Holds
X-Terragucci-Signature	sha256= and the hex HMAC-SHA256 of the raw body, with the key notify.webhook_key names
X-Terragucci-Event	the event
X-Terragucci-Delivery	the id

An event is never posted unsigned. Check the signature over the bytes received, before parsing them.

Fields

Field	Holds
schema	terragucci.notify/v1. It changes only when a field is removed or changes meaning; new fields can appear without a bump.
id	sha256 over the project, the wave, the event and the set digest (the commit when the wave has none): the same for every post of one wave’s event about one digest, so a re-run’s post can be dropped
event	waiting, refused or failed
sent_at	when the job posted it
project	the repo as <host>/<path>
forge, repo, sha	the forge, the repo’s path on it, and the commit the wave applied
pr	the pull or merge request, when a comment’s apply posted it
wave, roots	the wave, and its roots; for a refused or denied wave the roots that moved or were denied, for a failed one the roots that failed
run_url, report_url	the run, and the wave’s report when reports serves one
outcome	the stage’s outcome as it wrote it, with the terragucci approve command that approves a waiting wave

The JSON Schema ships with the package as @intentius/terragucci/notify.schema.json.