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

# Notifications

A monitor's `delivery` says where changes go. The changes feed always has them; a webhook and email recipients are optional.

```json theme={null}
{
  "delivery": {
    "webhook": { "url": "https://yourdomain.com/webhook", "secret": "replace-with-a-secret" },
    "email": { "to": ["alerts@yourdomain.com"] }
  }
}
```

Two events are sent: `monitor.changes`, once per check that found changes, and `monitor.paused`, when the monitor pauses itself for lack of credits or after repeated failures.

## Webhooks

Each event is one `POST` with a JSON body. Delivery retries on failure: five attempts, 1 minute, 5 minutes, 30 minutes and 2 hours apart. Any `2xx` answer counts as delivered; redirects are not followed. `GET /monitors/{id}/deliveries` lists the attempts.

> [!NOTE]
>
> The URL must be public: loopback, private and link-local addresses are refused.

### Headers

| Header | Value |
| - | - |
| `X-HasData-Event` | `monitor.changes` or `monitor.paused` |
| `X-HasData-Delivery` | The delivery id, the same across retries. Use it to ignore a duplicate. |
| `X-HasData-Timestamp` | Unix time, seconds |
| `X-HasData-Signature` | `sha256=<hex>`, when the monitor has a `secret`; see below. |

### Payload: `monitor.changes`

```json theme={null}
{
  "event": "monitor.changes",
  "monitor": { "id": "fe452d1e-…", "name": "AirPods price", "endpoint": "amazon_product", "goal": null },
  "check": { "id": "0c3b…", "trigger": "schedule", "checkedAt": "2026-11-12T12:00:05.000Z" },
  "changes": [
    {
      "resultId": 4812,
      "resourceId": "3f1c…",
      "resource": "B0D1XD1ZV3",
      "params": { "asin": "B0D1XD1ZV3" },
      "diff": { "kind": "fields", "changes": [{ "path": "product.price.currentPrice", "before": 249.99, "after": 198.16 }], "lists": [] },
      "patch": [ … ],
      "judge": null
    }
  ],
  "url": "https://app.hasdata.com/monitors/fe452d1e-…"
}
```

`changes` has one entry per changed resource. `patch` is cut to 80 lines; the full one is on the result in the API. For a page compared as text, `diff` is `null` and `patch` carries the lines.

### Payload: `monitor.paused`

```json theme={null}
{
  "event": "monitor.paused",
  "monitor": { "id": "fe452d1e-…", "name": "AirPods price", "endpoint": "amazon_product" },
  "reason": "no_credits",
  "url": "https://app.hasdata.com/monitors/fe452d1e-…"
}
```

### Verifying the Signature

With a `secret` on the monitor, every request is signed: `X-HasData-Signature` is `sha256=` followed by the hex HMAC-SHA256 of `<timestamp>.<raw body>` under the secret, where `<timestamp>` is the `X-HasData-Timestamp` header. Compute it over the raw bytes, before parsing the JSON.

```javascript Node.js theme={null}
const crypto = require('crypto');

function isSigned(req, rawBody, secret) {
  const timestamp = req.headers['x-hasdata-timestamp'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  const given = req.headers['x-hasdata-signature'] || '';
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
```

```python Python theme={null}
import hmac, hashlib

def is_signed(headers, raw_body: bytes, secret: str) -> bool:
    timestamp = headers["X-HasData-Timestamp"]
    expected = "sha256=" + hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(headers.get("X-HasData-Signature", ""), expected)
```

Reject requests whose timestamp is more than a few minutes old to rule out replays.

## Email

Each address in `email.to` (up to 10) gets a message per event: the changed resources with what changed, or the pause and its reason, each with a link to the monitor.

## The AI Judge

Not every change matters. With a `goal` on the monitor, every changed result is judged by an AI model against it, and the verdict is stored on the result:

```json theme={null}
{
  "goal": "Only price drops of 5% or more, or the product going out of stock."
}
```

```json theme={null}
"judge": { "matters": true, "reason": "The price dropped by 21%.", "model": "gpt-4.1-mini", "credits": 2 }
```

* The judge costs **2 credits per change** it looks at, charged with the check.
* Webhooks and emails are sent only for changes the judge found to matter; the feed keeps every change, and `GET /monitors/changes?matters=true` filters it.
* When the judge could not run, the verdict is `{ "error": "judge_unavailable" | "judge_failed" | "not_enough_credits", "message": "…" }` and the change is reported as if it mattered.

The dashboard shows the verdict and its reason next to each change.


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