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

# Webhooks

> Get a signed JSON POST when a batch, crawl, agent, extract or monitor reports. Verify the signature, handle retries and replay missed deliveries.

Set `webhook` on a job or monitor to get a JSON `POST` when it reports, instead of polling. Verify the signature before you trust a call. Any `2xx` answer acknowledges it. Everything on this page is free. Webhooks need an API key.

## Events

Every source sends the same top-level fields: `id` is the job or monitor, `event` says what happened, `eventId` names the call, and your `metadata` comes last.

| Source | Events |
| - | - |
| [Crawl](https://docs.stophy.dev/crawl/async.md#get-told-with-a-webhook), [Batch](https://docs.stophy.dev/batches/overview) | `started`, `page`, `completed`, `failed`, `cancelled` |
| [Agent](https://docs.stophy.dev/agent/overview) | the same, plus `action` for each step |
| [Extract](https://docs.stophy.dev/extract/overview) | `completed`, `failed` |
| [Monitor](https://docs.stophy.dev/monitors/checks-and-changes.md#webhooks) | `monitor.page`, `monitor.check.completed`, `monitor.changed`, `monitor.failed` |

A job sends `started` (a crawl gives `total`), then `page` as each page finishes, then one of `completed`, `failed` or `cancelled`. Use the last for final counts and cost.

```json theme={null}
{
  "id": "job_q6vkBosI0L0OennuqYa1iw",
  "event": "completed",
  "eventId": "evt_50c7394f-79a4-4863-954d-a9b3e3f8c28c",
  "status": "completed",
  "total": 1,
  "completed": 1,
  "failed": 0,
  "costUsd": 0.001,
  "metadata": { "project": "docs" }
}
```

* `failed` and `cancelled` have the same fields, and `failed` adds `message`.
* A `page` call holds `result` for a page that was read, or `error` for one that failed. When your address falls far behind, it holds only `url` and `resultOmitted: true`. Read that page with the job's status call.
* `eventId` stays the same when a call is sent again. Skip an ID you already handled.
* `creditsUsed` is an older field for the same cost as `costUsd`.

## Set a webhook

Send `webhook` as a URL, or as an object. For example, `"events": ["completed"]` limits the calls to successful completions.

| Field | Effect |
| - | - |
| `url` | Required. A public address that takes a `POST`. |
| `headers` | Up to 10 headers sent with every call. Names are letters, digits and hyphens up to 64 characters. Values are up to 1,000 characters, no line breaks. `content-type`, `user-agent`, `host`, `content-length` and `stophy-signature` are set by Stophy. Never kept with a delivery. |
| `metadata` | An object of up to 4,000 characters, returned in every call. |
| `events` | Which events to send. Default all. An extract takes only `completed` and `failed`. |

## Get the signing secret

One account secret signs the calls of every job. A [monitor](https://docs.stophy.dev/monitors/checks-and-changes.md#rotate-the-secret) can have its own. Keep it on your server.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/webhook/secret \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Read `data.secret`, and keep the whole string including the `whsec_` prefix. Send `{ "rotate": true }` to replace it. The old secret stops signing at once. For a planned rotation, accept both for a while. If the old one was exposed, accept only the new one.

## Verify signatures

Every call has these headers.

| Header | Value |
| - | - |
| `Stophy-Signature` | `t=<unix seconds>,v1=<hex>` |
| `Content-Type` | `application/json` |
| `User-Agent` | `Stophy-Webhook/1` |

`v1` is the HMAC-SHA256, in hex, of `<t>.<body>` with your secret as the key, where `<body>` is the exact request text. Read the raw body before you parse it. Compare in constant time. Reject a missing or malformed signature, or a `t` more than 5 minutes from your clock.

After verification, store the body by `eventId`. If the ID already exists, answer `2xx` without processing again. Answer before slow work.

## Retries

Answer `2xx` within 5 seconds. Redirects are not followed. A failed call is sent again after 0.5, 2 and 8 seconds, so 4 attempts in all. The calls of one job or monitor go in order, one at a time. After 3 failed deliveries in a row, the ones still waiting are skipped.

## Delivery history and retry

Records are kept for 30 days.

| Call | Does |
| - | - |
| `GET /v1/webhook/deliveries` | Lists newest first, under `data.deliveries`. Filters: `sourceType` (`batch`, `crawl`, `agent`, `monitor`, `extract`), `sourceId`, `status` (`delivered`, `failed`, `skipped`), `event`. `limit` up to 100 (default 20), and `cursor` until it is missing. |
| `GET /v1/webhook/deliveries/{id}` | One delivery, with the `payload` sent and `payloadKeptUntil`. |
| `GET /v1/webhook/deliveries/{id}/attempts` | Every try, oldest first: `at`, `ms`, `status`, `error`, and `trigger` (`auto` or `manual`). |
| `POST /v1/webhook/deliveries/{id}/retry` | Sends the original payload once to the current address and headers, signed with the current secret. Read `data.attempt` for the outcome, because the call succeeds even when your receiver rejects it. |

A delivery has `id` (`whd_` and a uuid), `sourceType`, `sourceId`, `event`, `url`, `status`, `attempts` and the time and status code of the last one.

## Limits and errors

Codes are on [Errors](https://docs.stophy.dev/api-reference/errors.md).

* The payload is kept 7 days, and never for zero data retention jobs or after you delete a batch's results.
* `404 notFound`: the delivery belongs to another account or is over 30 days old.
* `400 invalidRequest`: a `webhook.url` that is not public, a `webhook.events` name the source does not send, or a retry when the payload was not kept, is over 7 days old, or the monitor was deleted or has no webhook.


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