> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyager.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks for cloud machines

> Get a signed POST at your own URL when a cloud machine is ready, a job on it ends, it pauses, it is lost or it is released, instead of polling.

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.

> [!NOTE]
>
> **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](https://docs.voyager.so/api/machines/machines.md) or [job](https://docs.voyager.so/api/machines/commands.md) 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.

| `type` | When | Extra fields |
| - | - | - |
| `machine.ready` | The machine is ready after a lease, a resume or a replacement. | |
| `machine.job.succeeded` | A job on it exited with `0`. | |
| `machine.job.failed` | A job on it failed, was canceled or was lost with its machine. `data.status` and `data.error` say which. | |
| `machine.paused` | It paused. | `reason`: `user`, `idle`, `ttl`, `budget`, `credits` or `unresponsive` |
| `machine.lost` | The GPU host lost it. | `replaced`: `true` when a replacement is starting (a `machine.ready` follows), else it stays paused |
| `machine.released` | It was released. `data.cost` is final. | |

A budget stop is `machine.paused` with `reason: "budget"`. [Concepts](https://docs.voyager.so/api/machines/concepts.md#machine-states) explains each state.

## Set it up

**1. Create the workspace's secret**

```sh theme={"system"}
curl -s -X POST https://api.voyager.so/v1/machines/webhook-secret \
  -H "Authorization: Bearer $VOYAGER_API_KEY"
```

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**

```sh theme={"system"}
curl -s https://api.voyager.so/v1/machines \
  -H "Authorization: Bearer $VOYAGER_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"preset": "render-lite", "webhook_url": "https://hooks.example.com/voyager"}'
```

`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](https://www.standardwebhooks.com): `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:

```python Python theme={"system"}
import base64, hashlib, hmac, os, time

def verify(headers: dict, body: bytes) -> bool:
    secret = os.environ["VOYAGER_WEBHOOK_SECRET"]  # whsec_…
    key = base64.b64decode(secret.removeprefix("whsec_"))
    event_id, stamp = headers["webhook-id"], headers["webhook-timestamp"]
    if abs(time.time() - int(stamp)) > 300:  # refuse replays of old requests
        return False
    signed = f"{event_id}.{stamp}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    # Several space-separated signatures while a secret is being rotated: any one may match.
    return any(
        part.startswith("v1,") and hmac.compare_digest(part[3:], expected)
        for part in headers["webhook-signature"].split()
    )
```

```javascript JavaScript theme={"system"}
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(headers, body /* the raw body, a Buffer */) {
  const key = Buffer.from(process.env.VOYAGER_WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64");
  const id = headers["webhook-id"];
  const stamp = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(stamp)) > 300) return false;
  const expected = createHmac("sha256", key)
    .update(Buffer.concat([Buffer.from(`${id}.${stamp}.`), body]))
    .digest();
  return headers["webhook-signature"].split(" ").some((part) => {
    if (!part.startsWith("v1,")) return false;
    const given = Buffer.from(part.slice(3), "base64");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}
```

The [Standard Webhooks libraries](https://github.com/standard-webhooks/standard-webhooks) 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

> [card] [Concepts](https://docs.voyager.so/api/machines/concepts.md)
>
> What each machine state means, bills and keeps.

> [card] [Machines and cost](https://docs.voyager.so/api/machines/machines.md)
>
> Every lease option, pause, resume and release.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.