# Webhooks

Quivvo can send a signed HTTP POST to your server when a machine changes state, so you don't have to poll. Register a URL with the API, and keep the secret it returns.

```bash
curl -X POST https://tryquivvo.com/api/v1/webhooks \
  -H "Authorization: Bearer $QUIVVO_API_KEY" -H "content-type: application/json" \
  -d '{"url":"https://example.com/hooks/quivvo"}'
```

A workspace can have 10 webhooks. The URL must be public `https`, up to 2048 characters. Private, loopback and link-local addresses, internal names and a username or password in the URL are refused, and a name that resolves to a private address isn't delivered to. Redirects aren't followed, so point it at the final address.

## What events are there?

| Event | When |
| --- | --- |
| `machine.ready` | A machine finished booting |
| `machine.suspended` | A machine suspended and kept its memory, by request or because it was idle |
| `machine.stopped` | A machine stopped, including a suspend that couldn't keep memory and became a stop |
| `machine.failed` | A machine failed to boot or crashed |
| `machine.deleted` | A machine was deleted |

Pass `events` when registering to receive only some of them.

## How do I verify a delivery?

Each POST carries a `Quivvo-Signature: t=<unix>,v1=<hex>` header. Compute HMAC-SHA256 of `t + "." + body` with your secret and compare it to `v1`. The body looks like this:

```json
{ "id": "evt_...", "type": "machine.ready", "created_at": "...", "data": { "machine": {} } }
```

`data.machine` is the same object the [REST API](https://tryquivvo.com/docs/api#objects) returns.

Deliveries are best effort and aren't retried yet, so treat webhooks as a hint and read the machine's state when it matters.