Subscribe
Setwebhook_url and webhook_event_types when you create the monitor or update it. A monitor sends only the event types you list. The default subscription is ["monitor.field.changed"].
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.
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 anestablishedevent, 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.
monitor.field.changed and monitor.execution.completed to receive every successful first-run result.
Row notification payload
The payload identifies the check but does not include the changed values. Read them with List row events, filtered to the check:
monitor.execution.completed notification, use the same endpoint with include_completions=true:
established event per value found, with the value in current_value, and a completion event whose payload looks like:
Whole-monitor completion
Subscribe tomonitor.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.
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.
Read only the rows this run changed using Get a run’s changed rows, with the notification’s run_id:
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.
- A notification can arrive more than once. Signed notifications carry
Sixtyfour-Event-Type, the event type, andSixtyfour-Event-Id, the row notification’sevent_group_idor the whole-monitor notification’srun_id; use the pair to deduplicate. Unsigned notifications carry neither header: deduplicate on the body’stypewith itsevent_group_idorrun_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-eventswitheventset to a monitor event type, such asmonitor.field.changed, andurlset to an HTTPS receiver. The sample has the production payload and signing, but itsmonitor_idandrow_iddo 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 usingmonitor_id, row_id, and event_group_id from the payload. The examples process field changes.
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 Settings → Webhooks.