Skip to main content
Give a machine a 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

The answer holds 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: 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:
The Standard Webhooks libraries do the same in one call.

Delivery

  • Answer 2xx quickly. Any 2xx marks 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 use created_at or a fresh GET when order matters.
  • Your URL must be https on 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-secret again 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-secret stops signing. Events not yet delivered are dropped, and leases with a webhook_url are refused until a new secret exists.
Only workspace owners and admins can create, rotate or delete the secret. Any member can see whether one exists.

Next

Concepts

What each machine state means, bills and keeps.

Machines and cost

Every lease option, pause, resume and release.