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

# Monitor Notifications (Legacy)

> Webhook notifications a monitor sends after each check, their payload, and how to read the events behind them.

> [!NOTE]
>
> This page documents the original routes, which keep working. For new integrations, use the `/v1` routes in [Monitor Notifications](https://docs.sixtyfour.ai/api-reference/monitors/monitor-notifications.md). [Legacy](https://docs.sixtyfour.ai/api-reference/legacy.md) maps each original route to its `/v1` replacement.

Get told when a monitored field changes or a check fails, instead of polling. A monitor can notify you after each row check or after all selected rows finish a run. Your receiver reads row events or downloads the whole table from the API.

[LinkedIn monitors](https://docs.sixtyfour.ai/api-reference/legacy/linkedin-monitors.md) use the same subscriptions and notification payloads.

## Subscribe

Set `webhook_url` and `webhook_event_types` when you [create the monitor](https://docs.sixtyfour.ai/api-reference/legacy/monitors-endpoints.md#create-monitor) or [update it](https://docs.sixtyfour.ai/api-reference/legacy/monitors-endpoints.md#update-monitor). A monitor sends only the event types you list. The default subscription is `["monitor.field.changed"]`.

| Event type | Sent when |
| - | - |
| `monitor.field.changed` | A row check reported at least one `change` event. |
| `monitor.execution.completed` | A row check succeeded without a `change` event, including a first check that only establishes initial values. |
| `monitor.execution.failed` | A row check could not run. The next check re-examines the same time window. |
| `monitor.run.completed` | Every row selected for one monitor run finished. Sent once per run, with row counts. |

The three row event types send at most one notification per row per check. `webhook_url` must be a public HTTPS or HTTP address.

Skipped checks send no row notification. A check is skipped when your balance cannot cover it, which records an `error` event on the row, or when the team's spend limit is reached, which records nothing. A row's `last_run_at` advances only when a check of that row completes, so compare it with the monitor's frequency to catch skipped rows. The monitor's own `last_run_at` advances at the start of every tick.

LinkedIn monitors handle a low balance differently; see [LinkedIn check behavior](https://docs.sixtyfour.ai/api-reference/legacy/linkedin-monitors.md#check-behavior).

### First-run notifications

There is no separate initial-findings event. A row missing watched values gets a full first check:

* If it only fills in missing values, it sends `monitor.execution.completed`. Each value found is recorded as an `established` event, which is not a change.
* If it finds that a supplied value is out of date, it sends `monitor.field.changed`.
* If it fails, it sends `monitor.execution.failed`.

Rows that supply every watched value skip setup and send nothing at creation; their first check runs on the schedule. Subscribe to both `monitor.field.changed` and `monitor.execution.completed` to receive every successful first-run result.

## Row notification payload

```json theme={null}
{
  "type": "monitor.field.changed",
  "monitor_id": "d5a8c2f1-7e6b-4a93-b012-8f6e3d9c5a42",
  "row_id": "8c3e1f2a-6b4d-4c9e-a1f7-2e5d9b3c7a10",
  "event_group_id": "a7d2e9f1-3c5b-4e8a-9b1d-6f4c2e8a0b37",
  "metadata": { "portfolio_id": "p_42" }
}
```

| Field | Description |
| - | - |
| `type` | The event type. |
| `monitor_id` | The ID of the monitor containing the checked row. Use it as `{monitor_id}` in the events URL. |
| `row_id` | The ID of the row that was checked, used as `{row_id}` in the events URL. |
| `event_group_id` | Identifies one check of the specified row. Each check gets a new ID; all events from that check share it. |
| `metadata` | The monitor's `metadata`, echoed so you can route the notification without a lookup. It includes any [keys Sixtyfour adds](https://docs.sixtyfour.ai/api-reference/legacy/monitors-endpoints.md#metadata). |

The payload identifies the check but does not include the changed values. Read them with [List row events](https://docs.sixtyfour.ai/api-reference/legacy/monitors-endpoints.md#list-row-events), filtered to the check:

```http theme={null}
GET https://api.sixtyfour.ai/monitors/{monitor_id}/rows/{row_id}/events?event_group_id={event_group_id}&limit=500
```

For a `monitor.execution.completed` notification, use the same endpoint with `include_completions=true`:

```http theme={null}
GET https://api.sixtyfour.ai/monitors/{monitor_id}/rows/{row_id}/events?event_group_id={event_group_id}&include_completions=true&limit=500
```

On a first check with no changes, the response holds one `established` event per value found, with the value in `current_value`, and a `completion` event whose `payload` looks like:

```json theme={null}
{
  "first_run": true,
  "recheck_ran": true,
  "fields_established": 1
}
```

## Whole-monitor completion

Subscribe to `monitor.run.completed` to receive one notification after every row selected for a run has finished, including the initial run. Use it alone (`"webhook_event_types": ["monitor.run.completed"]`) or alongside row events.

```json theme={null}
{
  "type": "monitor.run.completed",
  "monitor_id": "d5a8c2f1-7e6b-4a93-b012-8f6e3d9c5a42",
  "run_id": "c93dc1be-fdb7-4b36-9f74-23b284eaf56e",
  "completed_at": "2026-10-01T10:00:00+00:00",
  "rows": {
    "total": 100,
    "succeeded": 97,
    "skipped": 3
  },
  "metadata": { "portfolio_id": "p_42" }
}
```

| Field | Description |
| - | - |
| `monitor_id` | The monitor whose run finished. |
| `run_id` | Identifies this whole-monitor run. Stable across delivery retries; use with `type` to deduplicate. |
| `completed_at` | When the run finished, as ISO 8601. The same on every delivery attempt. |
| `rows.total` | Number of active rows selected at the start of the run. Excluded rows are not counted. |
| `rows.succeeded` | Rows whose check succeeded, with or without changes. |
| `rows.skipped` | Rows without a confirmed successful check, including errors and checks skipped because a spending limit was reached. |
| `metadata` | The monitor's `metadata` at delivery time, including any [keys Sixtyfour adds](https://docs.sixtyfour.ai/api-reference/legacy/monitors-endpoints.md#metadata), or `null` when unset. |

The notification means the run finished, not that every row was refreshed: skipped rows keep their previous values. `rows.succeeded + rows.skipped` equals `rows.total`.

No run notification is sent when the monitor is paused or cancelled, or has no active rows, when the run starts. Pausing a monitor mid-run does not stop that run.

A `failed` run sends no notification; see [List monitor runs](https://docs.sixtyfour.ai/api-reference/legacy/monitors-endpoints.md#list-monitor-runs).

Read only the rows this run changed using [Get a run's changed rows](https://docs.sixtyfour.ai/api-reference/legacy/monitors-endpoints.md#get-a-runs-changed-rows), with the notification's `run_id`:

```http theme={null}
GET https://api.sixtyfour.ai/monitors/{monitor_id}/runs/{run_id}/changes
```

Or download the whole table using [Download snapshot](https://docs.sixtyfour.ai/api-reference/legacy/monitors-endpoints.md#download-snapshot):

```http theme={null}
GET https://api.sixtyfour.ai/monitors/{monitor_id}/snapshots/{completed_at}
```

URL-encode `completed_at` for the path. The CSV holds every row as of that time, including switched-off rows, so it can have more rows than `rows.total`. Use `snapshots/latest` for current values. A run notification has no `row_id` or `event_group_id`, and `run_id` is not a filter for row events.

## Delivery

* Notifications are signed when your organization has a signing secret. See [Signing Secrets & Verification](https://docs.sixtyfour.ai/api-reference/webhooks/signing-secrets.md).
* A notification can arrive more than once. Signed notifications carry `Sixtyfour-Event-Type`, the event type, and `Sixtyfour-Event-Id`, the row notification’s `event_group_id` or the whole-monitor notification’s `run_id`; use the pair to deduplicate. Unsigned notifications carry neither header: deduplicate on the body's `type` with its `event_group_id` or `run_id`.
* A failed delivery is retried with exponential backoff, up to 5 attempts in total. Each attempt times out after 10 seconds.
* A notification that cannot be delivered does not affect or rerun the check. Its events are stored and readable from the API.
* To send a sample notification to your receiver, call `POST /webhooks/test-events` with `event` set to a monitor event type, such as `monitor.field.changed`, and `url` set to an HTTPS receiver. The sample has the production payload and signing, but its `monitor_id` and `row_id` do not belong to a real monitor, so there are no events to read for it.

## Example receiver

Verify each notification against its raw body, then read the check's events using `monitor_id`, `row_id`, and `event_group_id` from the payload. The examples process field changes.

> [!NOTE]
>
> This receiver requires your organization to have a webhook signing secret. Without one, notifications arrive unsigned and this receiver rejects them with `400`. Generate a secret in [Webhooks settings](https://app.sixtyfour.ai/settings/webhooks).

```python Python theme={null}
import hashlib
import hmac
import json
import os
import time

import requests
from flask import Flask, abort, request

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.sixtyfour.ai"
SECRET = os.environ["SIXTYFOUR_WEBHOOK_SECRET"]
TOLERANCE = 300

app = Flask(__name__)

def verify(raw: bytes, header: str, secret: str) -> bool:
    parts = [p.strip() for p in header.split(",")]
    try:
        t = int(next(p.split("=", 1)[1] for p in parts if p.startswith("t=")))
    except (StopIteration, ValueError):
        return False
    if abs(int(time.time()) - t) > TOLERANCE:
        return False
    expected = hmac.new(
        secret.encode("utf-8"), f"{t}.".encode("utf-8") + raw, hashlib.sha256
    ).hexdigest()
    return any(
        p.startswith("v1=") and hmac.compare_digest(expected, p.split("=", 1)[1])
        for p in parts
    )

@app.post("/hooks/sixtyfour")
def monitor_notification():
    raw = request.get_data()  # raw bytes, before JSON parse
    if not verify(raw, request.headers.get("Sixtyfour-Signature", ""), SECRET):
        abort(400)
    body = json.loads(raw)
    if body["type"] != "monitor.field.changed":
        return "", 204

    events = requests.get(
        f"{BASE_URL}/monitors/{body['monitor_id']}/rows/{body['row_id']}/events",
        headers={"x-api-key": API_KEY},
        params={"event_group_id": body["event_group_id"], "limit": 500},
    )
    events.raise_for_status()
    for event in events.json():
        if event["event_type"] == "change":
            print(event["field"], event["previous_value"], "->", event["current_value"])
    return "", 204
```

```javascript JavaScript theme={null}
import crypto from "crypto";
import express from "express";

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.sixtyfour.ai";
const SECRET = process.env.SIXTYFOUR_WEBHOOK_SECRET;
const TOLERANCE = 300;
const app = express();
app.use(express.raw({ type: "application/json" }));

function verify(raw, header, secret) {
  const parts = header.split(",").map((p) => p.trim());
  const tPart = parts.find((p) => p.startsWith("t="));
  if (!tPart) return false;
  const t = parseInt(tPart.slice(2), 10);
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(Buffer.concat([Buffer.from(`${t}.`), raw]))
    .digest("hex");
  return parts.some((p) => {
    if (!p.startsWith("v1=")) return false;
    const got = Buffer.from(p.slice(3), "utf8");
    const exp = Buffer.from(expected, "utf8");
    return got.length === exp.length && crypto.timingSafeEqual(got, exp);
  });
}

app.post("/hooks/sixtyfour", async (req, res) => {
  if (!verify(req.body, req.header("Sixtyfour-Signature") || "", SECRET)) {
    return res.status(400).send("invalid signature");
  }
  const body = JSON.parse(req.body.toString("utf8"));
  if (body.type !== "monitor.field.changed") return res.sendStatus(204);

  const params = new URLSearchParams({ event_group_id: body.event_group_id, limit: "500" });
  const response = await fetch(
    `${BASE_URL}/monitors/${body.monitor_id}/rows/${body.row_id}/events?${params}`,
    { headers: { "x-api-key": API_KEY } },
  );
  if (!response.ok) return res.status(502).send("could not read events");
  const events = await response.json();
  for (const event of events.filter((e) => e.event_type === "change")) {
    console.log(event.field, event.previous_value, "->", event.current_value);
  }
  res.sendStatus(204);
});

app.listen(3000);
```

## Pricing

See [Credit Costs](https://docs.sixtyfour.ai/guides/credits-and-pricing.md#monitors) for more information.

## Related

* [Monitors Overview](https://docs.sixtyfour.ai/api-reference/legacy/monitors-overview.md)
* [Outgoing Webhooks](https://docs.sixtyfour.ai/api-reference/webhooks/outgoing.md)
* [Handling Errors](https://docs.sixtyfour.ai/api-reference/legacy/errors.md)


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