Webhook events
Every event a webhook subscription can receive. Subscribe to a list of
types, or to * for all of them. How to receive them is in
Webhooks; verifying the signature is in
Verifying signatures.
| Event | For | What happened |
|---|---|---|
agent.work_available |
Agents | Steps an agent may claim became ready: at the start of a run, after an approval was decided, after a wait ended, or when an agent’s lease lapsed. |
approval.requested |
People | An approval opened and is waiting for its approvers. |
approval.escalated |
People | An approval reached its timeout undecided and escalated. |
approval.expired |
People | An escalated approval reached its escalation_timeout undecided. |
approval.decided |
Approvals | An approval was decided by its approvers. |
step.blocked |
People | A step needs a person: it was handed off (on_failure: handoff, or runbook step request-human) or reported blocked. |
step.completed |
Steps | A step reached a final status. |
step.reminder |
People | A step has been open for remind_after (and every remind_every after). |
step.escalated |
People | A step has been open for escalate_after and escalated to escalate_to. |
execution.queued |
Runs | A start was queued behind the runbook’s concurrency limit. |
execution.started |
Runs | A run started (or a queued run got its slot). |
execution.completed |
Runs | A run ended. |
memory.proposed |
Memory | An agent proposed a memory entry for people to accept or reject. |
memory.saved |
Memory | An agent saved a memory entry directly, so people can follow (and revert) what agents write. |
memory.edited |
Memory | An agent edited an existing memory entry. |
runbook.published |
Runbooks | A runbook version was published. |
webhook.test |
Testing | Sent by runbook webhook test (or the API’s test route) to one subscription, to check the receiver end to end. |
Events marked People are notices for people (approvers, assignees, escalations). When one reaches no subscriber, the run page says so.
The envelope
Section titled “The envelope”Every delivery is a POST with a JSON body of this shape. Payloads carry
identifiers, recipients, links and facts about the event, never
credentials or secrets.
| Field | Meaning |
|---|---|
id |
The event ID (evt_…). The same on every retry of the event: deduplicate on it |
type |
The event type |
version |
The envelope version, 1 |
created_at |
When the event happened, RFC 3339 UTC with milliseconds |
org, project |
The organization and project IDs |
execution |
The run: id, title, runbook, runbook_version_id, runbook_version and url; null for project events |
sequence |
The run event that caused it; orders one run’s events. 0 when there is no run event |
data |
The event’s own facts, below |
Headers
Section titled “Headers”| Header | Value |
|---|---|
Content-Type |
application/json |
User-Agent |
TheRunbook-Webhooks/1 |
Runbook-Event-Id |
The event ID, as in the body |
Runbook-Event-Type |
The event type |
Runbook-Delivery-Id |
This delivery (whd_…); a redelivery gets a new one |
Runbook-Timestamp |
Unix seconds when this attempt was signed |
Runbook-Signature |
v1=<hex HMAC-SHA256>, one per active secret, comma-separated |
Delivery rules
Section titled “Delivery rules”| Rule | Value |
|---|---|
| A delivery succeeds on | A 2xx within 10 seconds |
| Retried on | Timeouts, connection errors, 5xx, 408 and 429 |
| Failed at once on | Any other status, a redirect (never followed) or a target that fails the address checks |
| Retries stop after | 24 hours from the delivery’s creation |
| Signature timestamp tolerance | 5 minutes |
| Secret rotation overlap | 24 hours, during which both secrets sign |
| A subscription is disabled after | 3 days of continuous failure |
| Delivery log kept | 90 days |
| Subscriptions per project | 20 |
| Subscription URL | At most 2,048 bytes |
| Signing secrets | Start with whsec_; shown once, on create and on rotate |
The wait before each retry doubles, up to a ceiling:
| Retry | Waits |
|---|---|
| 1 | 30 s |
| 2 | 1 min |
| 3 | 2 min |
| 4 | 4 min |
| 5 | 8 min |
| 6 | 16 min |
| 7 | 32 min |
| 8 | 64 min |
| 9 and later | 2 hours |
Agents
Section titled “Agents”agent.work_available
Section titled “agent.work_available”Steps an agent may claim became ready: at the start of a run, after an
approval was decided, after a wait ended, or when an agent’s lease lapsed.
Subscribe a launcher to it to start (or wake) an agent. data.reason says
why (initial, approval_decided, timer, signal, auto_decision,
lease_expired or cleanup); data.params is the runbook’s
spec.agents.params, passed through untouched.
{ "id": "evt_01JD2X6Q2C4V7T9M3K8B5N1R0S", "type": "agent.work_available", "version": 1, "created_at": "2026-11-18T09:30:12.418Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 4, "data": { "reason": "initial", "ready_steps": [ { "step_run_id": "sr_01JD2X6Q1B3N5P7R9T1V3X5Z7A", "path": "check_health", "title": "Check health" } ], "params": { "repo": "acme/api", "workflow": "runbook-resume.yml" } }}Approvals
Section titled “Approvals”approval.requested
Section titled “approval.requested”An approval opened and is waiting for its approvers. recipients are the
people it was sent to (teams are expanded to their members).
{ "id": "evt_01JD2X9A7F0H2K4M6P8R0T2V4X", "type": "approval.requested", "version": 1, "created_at": "2026-11-18T09:41:03.077Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 11, "data": { "step_run_id": "sr_01JD2X9A6E9G1J315N7Q9S1V3W", "recipients": [ { "type": "user", "id": "usr_01JC0000000000000000000A1C" }, { "type": "user", "id": "usr_01JC0000000000000000000B0B" } ], "link": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }}approval.escalated
Section titled “approval.escalated”An approval reached its timeout undecided and escalated. recipients
are the people it now goes to; targets the configured escalate_to
(teams and users).
{ "id": "evt_01JD2YB4C6E8G0J214N6Q8S0V2", "type": "approval.escalated", "version": 1, "created_at": "2026-11-18T10:11:03.512Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 14, "data": { "step_run_id": "sr_01JD2X9A6E9G1J315N7Q9S1V3W", "recipients": [{ "type": "user", "id": "usr_01JC0000000000000000000CAR" }], "link": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "targets": [{ "type": "team", "id": "team_01JC00000000000000000001DS" }] }}approval.expired
Section titled “approval.expired”An escalated approval reached its escalation_timeout undecided. The run
pauses or the step fails, by on_expired.
{ "id": "evt_01JD30C1D3F5H7K9M1P3R5T7V9", "type": "approval.expired", "version": 1, "created_at": "2026-11-18T12:11:03.640Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 17, "data": { "step_run_id": "sr_01JD2X9A6E9G1J315N7Q9S1V3W", "recipients": [{ "type": "user", "id": "usr_01JC0000000000000000000CAR" }], "link": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "targets": [{ "type": "team", "id": "team_01JC00000000000000000001DS" }] }}approval.decided
Section titled “approval.decided”An approval was decided by its approvers. option is the chosen option’s
ID; signers the people whose decisions counted (as many as min).
Automatic timeout decisions don’t send this event.
{ "id": "evt_01JD2XA2B4D6F8H0K2M4P6R8T0", "type": "approval.decided", "version": 1, "created_at": "2026-11-18T09:52:40.233Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 12, "data": { "option": "keep", "decided_by": "usr_01JC0000000000000000000B0B", "signers": ["usr_01JC0000000000000000000B0B"], "automatic": false, "step_run_id": "sr_01JD2X9A6E9G1J315N7Q9S1V3W" }}step.blocked
Section titled “step.blocked”A step needs a person: it was handed off (on_failure: handoff, or
runbook step request-human) or reported blocked. reason is the
report’s status (failed, blocked, …).
{ "id": "evt_01JD2XC9E1G3J517N9Q1S3V5W7", "type": "step.blocked", "version": 1, "created_at": "2026-11-18T09:47:55.901Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 9, "data": { "step_run_id": "sr_01JD2XC8D0F2H4K6M8P0R2T4V6", "recipients": [{ "type": "user", "id": "usr_01JC0000000000000000000A1C" }], "reason": "failed", "link": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }}step.completed
Section titled “step.completed”A step reached a final status. path is its place in the runbook
(regions[2].error_rate inside a foreach); verdict is set on checks.
{ "id": "evt_01JD2X7K3M5P7R9T1V3X5Z7B9D", "type": "step.completed", "version": 1, "created_at": "2026-11-18T09:33:48.120Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 6, "data": { "status": "succeeded", "verdict": "pass", "path": "check_health", "step_run_id": "sr_01JD2X6Q1B3N5P7R9T1V3X5Z7A" }}step.reminder
Section titled “step.reminder”A step has been open for remind_after (and every remind_every after).
recipients are the step’s current people.
{ "id": "evt_01JD31D2F4H6K8M0P2R4T6V8X0", "type": "step.reminder", "version": 1, "created_at": "2026-11-18T11:47:55.004Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 15, "data": { "step_run_id": "sr_01JD2XC8D0F2H4K6M8P0R2T4V6", "recipients": [{ "type": "user", "id": "usr_01JC0000000000000000000A1C" }], "link": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }}step.escalated
Section titled “step.escalated”A step has been open for escalate_after and escalated to escalate_to.
recipients are the expanded people; targets the configured teams and
users.
{ "id": "evt_01JD33E3G5J719N1Q3S5V7W9Y1", "type": "step.escalated", "version": 1, "created_at": "2026-11-19T09:47:55.010Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 21, "data": { "step_run_id": "sr_01JD2XC8D0F2H4K6M8P0R2T4V6", "recipients": [{ "type": "user", "id": "usr_01JC0000000000000000000CAR" }], "link": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "targets": [{ "type": "team", "id": "team_01JC00000000000000000001DS" }] }}execution.queued
Section titled “execution.queued”A start was queued behind the runbook’s concurrency limit. sequence is
0: the run has no events yet.
{ "id": "evt_01JD2X6PZ6S9F3X5Z7B1D4G6J8", "type": "execution.queued", "version": 1, "created_at": "2026-11-18T09:30:11.902Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 0, "data": { "status": "queued", "concurrency_key": "deploy-api" }}execution.started
Section titled “execution.started”A run started (or a queued run got its slot).
{ "id": "evt_01JD2X6Q0A2C4E6G8J012N4Q6S", "type": "execution.started", "version": 1, "created_at": "2026-11-18T09:30:12.401Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 1, "data": { "status": "running" }}execution.completed
Section titled “execution.completed”A run ended. status is succeeded, failed or cancelled; result
holds the run’s outputs.
{ "id": "evt_01JD2XF0H2K4M6P8R0T2V4X6Z8", "type": "execution.completed", "version": 1, "created_at": "2026-11-18T09:58:31.776Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 19, "data": { "status": "succeeded", "result": { "result": "kept" } }}Memory
Section titled “Memory”memory.proposed
Section titled “memory.proposed”An agent proposed a memory entry for people to accept or reject. Only
identifiers: read the entry (untrusted text) through the API. From a run,
data names the step run; from the memory API, it also carries
revision, runbook, actor_kind and actor, and execution is
null.
{ "id": "evt_01JD2XD5F7H9K1M3P5R7T9V1X3", "type": "memory.proposed", "version": 1, "created_at": "2026-11-18T09:49:02.318Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 10, "data": { "memory_id": "mem_01JD2XD5E6G8J012N4Q6S8V0W2", "step_run_id": "sr_01JD2XC8D0F2H4K6M8P0R2T4V6" }}memory.saved
Section titled “memory.saved”An agent saved a memory entry directly, so people can follow (and revert)
what agents write. The same two shapes as memory.proposed.
{ "id": "evt_01JD2XE6G8J012N4Q6S8V0W2Y4", "type": "memory.saved", "version": 1, "created_at": "2026-11-18T09:50:13.007Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": null, "sequence": 0, "data": { "memory_id": "mem_01JD2XE6F7H9K1M3P5R7T9V1X3", "revision": 1, "runbook": "rb_01JC9Z0000000000000000000A", "actor_kind": "agent", "actor": "tok_01JC0000000000000000000AGT" }}memory.edited
Section titled “memory.edited”An agent edited an existing memory entry. The same two shapes as
memory.proposed.
{ "id": "evt_01JD2XF7H9K1M3P5R7T9V1X3Z5", "type": "memory.edited", "version": 1, "created_at": "2026-11-18T09:55:44.621Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": { "id": "exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7", "title": "Verify api", "runbook": "rb_01JC9Z0000000000000000000A", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3, "url": "https://runbooks.example.com/runs/exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7" }, "sequence": 18, "data": { "memory_id": "mem_01JD2XD5E6G8J012N4Q6S8V0W2", "step_run_id": "sr_01JD2XC8D0F2H4K6M8P0R2T4V6" }}Runbooks
Section titled “Runbooks”runbook.published
Section titled “runbook.published”A runbook version was published. Identifiers only, never the source;
execution is null. Subscriptions with a runbook filter receive it for
that runbook; tag-filtered subscriptions don’t.
{ "id": "evt_01JD2W0A2C4E6G8J012N4Q6S8V", "type": "runbook.published", "version": 1, "created_at": "2026-11-18T09:12:00.050Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": null, "sequence": 0, "data": { "runbook": "rb_01JC9Z0000000000000000000A", "runbook_slug": "post-deploy", "runbook_version_id": "rbv_01JD0000000000000000000003", "runbook_version": 3 }}Testing
Section titled “Testing”webhook.test
Section titled “webhook.test”Sent by runbook webhook test (or the API’s test route) to one
subscription, to check the receiver end to end.
{ "id": "evt_01JD2W1B3D5F7H9K1M3P5R7T9V", "type": "webhook.test", "version": 1, "created_at": "2026-11-18T09:14:27.388Z", "org": "org_01JC0000000000000000000001", "project": "prj_01JC0000000000000000000001", "execution": null, "sequence": 0, "data": { "webhook_id": "whk_01JD2W1A2C4E6G8J012N4Q6S8V", "message": "Test delivery from The Runbook." }}