Use case
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.Pricing
Notifications are free. See Credits & Pricing Guide for the cost of monitor checks.Errors
For error responses (400, 403, 404, etc.), see Handling Errors.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"]; delivery also requires a webhook_url.
Checks that are skipped send no row notification. A check is skipped when your balance cannot cover it, which also records an
error event on the row, or when the team’s spend limit is reached, which records nothing. To catch skipped checks, compare each row’s last_run_at with the monitor’s frequency, or list a row’s events with include_completions=true and look for gaps. A row’s last_run_at advances only when a check of that row completes. The monitor’s own last_run_at advances at the start of every tick, so it does not show skipped rows.
webhook_url must be a public HTTPS or HTTP address. You can change or clear it later with POST /monitors/{monitor_id}/update. Change webhook_event_types through the same endpoint to replace the subscription for every row. Omit the field to keep it unchanged, or send null to restore ["monitor.field.changed"]. Lists must be nonempty and contain only monitor.field.changed, monitor.execution.completed, monitor.execution.failed, or monitor.run.completed; duplicates collapse in first-occurrence order. Monitor and row responses include the effective subscription.
The three row event types send one notification per row per check when subscribed to the resulting event type.
monitor.run.completed sends one notification for the entire run. Subscribe to monitor.execution.completed to receive initial results and later checks that find no changes.First-run notifications
Rows missing watched values receive a full first check to establish starting values for future comparisons. Rows with all watched values supplied skip setup and send no execution notification at creation; their first check runs on the schedule and starts with the probe. A watched field that was blank or omitted in the input is recorded as anestablished event when its initial value is found. Establishing a value does not count as a change.
- If the first check succeeds without changing a prefilled value, it sends
monitor.execution.completedwhen subscribed. - If it changes a prefilled value, it sends
monitor.field.changedinstead ofmonitor.execution.completed. - If the check fails, it sends
monitor.execution.failedwhen subscribed. Skipped checks send no notification.
monitor.execution.completed and monitor.field.changed to receive successful first-run results whether fields start empty or prefilled. Subscribing only to changes and failures does not notify you when the first check simply establishes initial values.
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 for each initial field value found and a completion event. The established events contain the values in current_value; the completion event has a payload such as:
include_completions=true, completion events are hidden; established events are still returned.
Whole-monitor completion
Subscribe tomonitor.run.completed in webhook_event_types when creating a monitor to receive one notification after every row selected for that run has finished. This includes the initial run. The existing monitor.execution.completed event remains per row and only covers checks without changes.
To receive only whole-monitor notifications, include this field alongside rows, watched fields, and webhook_url:
This notification means the run finished, not that every row was refreshed. Check the counts before treating the whole table as refreshed; skipped rows may retain older values.
rows.succeeded + rows.skipped equals rows.total.
A monitor that is paused, deleted, or has no active rows when its run starts sends no run notification. Pausing a monitor after a run starts does not cancel that in-flight run. A run interrupted by workflow cancellation or a failed batch sends no run notification because it cannot establish that every row finished. Notification delivery failure does not rerun enrichment.
Download the whole table using Download snapshot:
completed_at for the path. This returns CSV with the values recorded by that time, including unchanged values and excluded rows. Because rows.total counts only active rows selected for this run, the CSV can contain more rows than the notification counts. Use snapshots/latest for current values, which may include later runs if delivery was delayed. These requests require your API key.
A run notification has no row_id or event_group_id; its run_id is not a filter for the row-events endpoint. Individual row notifications retain their own execution IDs. You can subscribe to the run event alone or alongside row events.
Delivery
- Notifications are signed when your organization has a signing secret. See Signing Secrets & Verification.
Sixtyfour-Event-Typecarries the event type andSixtyfour-Event-Idcarries the row notification’sevent_group_idor the whole-monitor notification’srun_id. Use the pair to deduplicate: a notification can arrive more than once.- A failed delivery is retried with exponential backoff. Each attempt times out after 10 seconds.
- A notification that cannot be delivered does not affect the check. Its events are stored and readable from the API.
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 below process field changes. Set MONITOR_IDS to a comma-separated list of monitor IDs to restrict this receiver; unset, it processes field changes from any monitor in the organization. An explicitly empty or whitespace-only list fails at startup. The signing secret verifies the sender, not which monitors this receiver handles.
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.