> ## 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.

# Checks, changes and webhooks

> Read what each monitor check found, with the diff of every changed page, or get it by signed webhook or email. Reads and webhooks are free.

Each check holds one result per page: `same`, `new`, `changed`, `removed` or `error`. A changed page comes with its diff. You can read it by polling, by [webhook](#webhooks) or by [email](#email). Reads are free, and a check is charged when it runs. See [Pricing](https://docs.stophy.dev/account/pricing.md).

## Checks

`GET /v1/monitor/{id}/checks` lists the checks of one monitor, newest first.

```bash theme={null}
curl "https://api.stophy.dev/v1/monitor/$MONITOR_ID/checks?limit=5" \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "bfdcccc0-40ed-4305-84fb-708ec7044e8b",
      "status": "completed",
      "trigger": "scheduled",
      "actualCostUsd": 0.001,
      "billingStatus": "confirmed",
      "summary": { "totalPages": 1, "same": 0, "changed": 0, "new": 1, "removed": 0, "error": 0 },
      "error": null
    }
  ]
}
```

| Field | Holds |
| - | - |
| `status` | `queued`, `running`, `completed`, `partial` (some pages failed), `failed` (every page failed), `skipped_overlap` or `skipped_no_credits`. A check `running` for 30 minutes shows as `failed`. |
| `trigger` | `scheduled`, or `manual` for [a run now](https://docs.stophy.dev/monitors/overview#run-pause-and-resume). |
| `scheduledFor`, `startedAt`, `finishedAt` | When it was due, started and ended. A manual check has no `scheduledFor`. |
| `estimatedCostUsd`, `actualCostUsd` | The estimate before extras, and the charge once it ended (`null` before). |
| `billingStatus` | `reserved` while running, `confirmed` once charged, `not_applicable` when skipped. |
| `summary` | Pages per outcome, out of `totalPages`. |
| `error` | Why it did not finish, or `null`. |

Filter with `status`, `limit` up to 100 (default 20) and `offset`. `GET /v1/monitor/{id}/checks/{checkId}` returns one check with `data.pages`, up to 100 per answer. Send `limit` and `skip`, follow `next` until `null`, or send `status` to keep one page status.

| Page field | Holds |
| - | - |
| `url`, `targetId` | The page and its target. |
| `status` | See below. |
| `statusCode`, `error` | What the page answered, or why it could not be read. |
| `judgment` | With a `goal`, see [Targets](https://docs.stophy.dev/monitors/targets.md#goal-and-judge). Otherwise `null`. |
| `diff` | `text` is a unified diff with 2 lines of context, cut at 20,000 characters. With `json` comparison, `json` maps each changed field to `previous` and `current`. `null` when unchanged. |
| `snapshot` | With `json` comparison, `json` holds the fields read. |
| `costUsd` | What the page cost. |

| Page `status` | Meaning |
| - | - |
| `new` | Read for the first time, or back after removal. On a monitor's first check this is the baseline and sends no event. For crawl and search targets, a page or result found later is a change and is sent. |
| `same` | Text equals the last read. Charged. |
| `changed` | Text differs from the last read. |
| `removed` | It answered `404` or `410`. Charged once. If it still does on the next check, it is `error`. |
| `error` | Could not be read. Free, retried on the next check. |

### Search results

For a search target each page is a result, and `metadata.searchStatus` says what happened to it.

| `searchStatus` | Meaning |
| - | - |
| `alert` | New to you. Reported as `new`. |
| `already_seen` | Already told or already judged. `same`, free. |
| `ignored` | The judge found it not meaningful. `same`, not looked at again. |
| `skipped` | The judge could not decide. `error`, looked at again next check. |

## Changes

`GET /v1/monitor/{id}/changes` lists one row per page per check, newest first. Query: `status` (a `changeStatus`), `url`, `limit` up to 100 (default 20), `cursor` from `next`. Rows hold `at`, `url`, `changeStatus` (`new`, `same`, `changed`, `removed`, or `null` with an `error` when unreadable), `diff`, `json` and `costUsd`.

Across monitors, `GET /v1/monitor/checks` (filters `monitorId`, `status`, `trigger`, `limit`, `cursor`, rows in `data.checks`) and `GET /v1/monitor/changes` (filters `monitorId`, `status`, `url`, `limit`, `cursor`, rows in `data.changes` with `id`, `monitorId`, `monitorName`) list everything. The change list leaves out the diff. `GET /v1/monitor/changes/{id}` reads one row with its `diff`.

## Webhooks

Add `webhook` on create, or set it later with `PATCH`. `PATCH` replaces it as a whole, and `"webhook": null` removes it. The fields, delivery format, signature check, retries and delivery history are on [Webhooks](https://docs.stophy.dev/webhooks.md). Choose `webhook.events`:

| Event | Sent when | Payload |
| - | - | - |
| `monitor.page` | A page changed, appeared or went away. | `url`, `changeStatus`, `at`, `diff`, `judgment`. |
| `monitor.check.completed` | A check ended, including a first check and one that found nothing. | `monitorId`, `checkId`, `status`, `summary`, `finishedAt`, `costUsd`. |
| `monitor.changed` | The same as `monitor.page`. | The same. |
| `monitor.failed` | A page failed 5 checks in a row, or your balance ran out. | `reason`, `at`, and for a page `url` and `failures` (5). |

With `targets` and `schedule` and no `events`, you get `monitor.page` and `monitor.check.completed`. A monitor made with the older `url`, `urls` and `interval` fields gets `monitor.changed` and `monitor.failed`. The first check of page targets sends no `monitor.page`, but it does send `monitor.check.completed`.

`changeStatus` is `changed`, `new` or `removed`. A `removed` page has only `url`, `changeStatus` and `at`. A search result also has `title`. With `json` comparison the event holds `json`. A `judgment` with `meaningful: false` is still sent. `actualCredits` on `monitor.check.completed` is an older field for `costUsd`.

### Rotate the secret

Until you rotate, a monitor's calls are signed with your account secret from `POST /v1/webhook/secret`. `POST /v1/monitor/{id}/webhook/rotate-secret` gives this monitor its own.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/monitor/$MONITOR_ID/webhook/rotate-secret \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

Store `data.secret` with its `whsec_` prefix. The old secret stops signing this monitor's calls at once, and your other jobs keep the account secret. A monitor with no webhook returns `400 invalidRequest`.

## Email

Set `notification.email` on create or update to get changes without a receiver.

| Field | Default | Effect |
| - | - | - |
| `enabled` | `false` | Send an email when a check finds a change. |
| `recipients` | `[]` | Up to 25 addresses. Your account address gets mail at once. Any other gets a confirmation link first and nothing until it is clicked. Every email has an unsubscribe link. |
| `includeDiffs` | `false` | Put each changed page's text in the email. |

`notification.email.recipientStates` shows `confirmed`, `pending` or `unsubscribed` for each recipient.

## Limits and errors

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

* `404 notFound`: a monitor, check or change id that does not exist, is not yours or has expired.
* `400 invalidRequest`: a `cursor` that is not the one from the last answer, `webhook.url` not public, or `webhook.events.0: Send one of: monitor.page, monitor.check.completed, monitor.changed, monitor.failed.`


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