Webhooks
The Runbook ships one generic, outbound webhook system and no vendor
integrations: your systems subscribe to the events they care about, and the
server POSTs a small, signed JSON envelope to them. Use it to start agents
when there’s work (agent.work_available), to page or chat when an approval
waits (approval.requested), or to feed run results into your own tools
(execution.completed).
Events are written to a durable outbox in the same transaction as the run change that caused them, so an event is never lost and never sent for a change that didn’t happen.
Subscribe
Section titled “Subscribe”-
Create a subscription in the project. It needs
webhooks:manage(a project admin):Terminal window runbook webhook create --project prod --name pager \--url https://hooks.example.com/runbook \--event approval.requested --event step.blocked --jsonThe response includes the signing secret (
whsec_…) once. Store it where your receiver can read it. -
Narrow it if you like:
--event '*'for every event type;--runbook rb_…(repeatable) for events of those runbooks only;--tag <tag>for runs with that tag (spec.execution.tags).
-
Check the receiver end to end:
Terminal window runbook webhook test whk_… --project prodrunbook webhook deliveries whk_… --project prodThe delivery log shows each attempt with its status code, latency and the start of the response body (redacted).
A project has at most 20 subscriptions. URLs are https and must resolve to
public addresses: private, loopback and link-local targets are refused when
the subscription is saved and again at each delivery, and redirects are never
followed. A self-hosted server can allow private and plain-http targets
with RUNBOOK_ALLOW_PRIVATE_WEBHOOK_TARGETS=true (for receivers on your own
network).
Receive
Section titled “Receive”A receiver should:
- Verify the signature on the raw body: Verifying signatures has the code.
- Deduplicate on the event ID (
Runbook-Event-Id, the body’sid). Delivery is at least once. - Order by
sequencewhen order matters: it orders one run’s events; deliveries can arrive out of order. - Answer
2xxwithin 10 seconds, and do slow work afterwards. Answer5xxwhen your own downstream call failed, so the event comes back.
Payloads hold identifiers, recipients, links and facts about the event, never credentials or secrets. An agent launcher mints execution credentials with its own service token (see Your own agent).
Manage
Section titled “Manage”| Task | Command |
|---|---|
| List subscriptions | runbook webhook list --project <p> |
| Change events, filters or URL | runbook webhook update <whk> --project <p> --event … |
| Pause or resume | runbook webhook update <whk> --project <p> --disable / --enable |
| Send one event again | runbook webhook redeliver <whd> --webhook <whk> --project <p> |
| Rotate the secret | runbook webhook rotate-secret <whk> --project <p> |
| Delete | runbook webhook delete <whk> --project <p> |