webhook_url and Voyager sends a signed event there every time its state changes. Your code learns that a render finished, or that a machine paused because it hit its budget, without polling.
Before you start: an
https URL on a public host that answers 2xx, and the workspace’s webhook secret. Only workspace owners and admins can create the secret.Events
Every event is a JSON body{id, type, created_at, data}. data is the machine or job as GET /v1/machines/{id} or GET /v1/machines/jobs/{id} returned it at that moment (a job’s output_tail is null). Read the live object if you need more.
A budget stop is
machine.paused with reason: "budget". Concepts explains each state.
Set it up
1
Create the workspace's secret
secret, a whsec_… value that is shown only this once. Store it where your receiver can read it. GET on the same path only says whether a secret exists.2
Lease with a webhook URL
POST /v1/machines/{id}/resume also takes webhook_url, which moves a machine’s events to a new URL from then on. A resume without one keeps the machine’s URL. A lease with a webhook_url in a workspace with no secret is refused with WEBHOOK_SECRET_REQUIRED: no event is ever sent unsigned.3
Verify each event
Every request carries three headers, as in Standard Webhooks: The Standard Webhooks libraries do the same in one call.
webhook-id (the event’s evt_… id), webhook-timestamp (Unix seconds) and webhook-signature. Check the signature over the raw body before you trust anything in it:Delivery
- Answer
2xxquickly. Any2xxmarks the event delivered. Voyager reads only the status, and an attempt that takes longer than 15 seconds counts as failed. Do slow work after you answer. - Retries: anything else, or no answer, is retried with backoff for 24 hours. Every retry carries the same
webhook-id. - At least once, in no fixed order. Deduplicate on
webhook-id, and usecreated_ator a freshGETwhen order matters. - Your URL must be
httpson a public host. Private, loopback and link-local addresses are refused when you lease and again on every attempt, and redirects are not followed.
GET /v1/machines/{id}/webhook-deliveries lists a machine’s last 50 events. Each row has id, type, state (pending, delivered or failed), attempts, the last attempt’s time, your receiver’s last status code or error, and the next try. Bodies and secrets are never listed.
Rotate or delete the secret
- Rotate:
POST /v1/machines/webhook-secretagain makes a new secret and returns it once. The old one keeps signing alongside it for 24 hours (rotating_until), so the header carries both signatures until you’ve moved your receiver over. - Delete:
DELETE /v1/machines/webhook-secretstops signing. Events not yet delivered are dropped, and leases with awebhook_urlare refused until a new secret exists.
Next
Concepts
What each machine state means, bills and keeps.
Machines and cost
Every lease option, pause, resume and release.