Skip to main content

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

Set webhook_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 an established 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.completed when subscribed.
  • If it changes a prefilled value, it sends monitor.field.changed instead of monitor.execution.completed.
  • If the check fails, it sends monitor.execution.failed when subscribed. Skipped checks send no notification.
The linked create-monitor example subscribes to the three row event types, including completion notifications. There is no separate initial-findings notification type. Subscribe to both 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:
The events endpoint returns 20 events by default and at most 500, with no pagination. The limit applies to the total number of returned events, including completion events when requested. Both path IDs come directly from the notification. No row-to-monitor lookup is required. For a monitor.execution.completed notification, use the same endpoint with include_completions=true:
The response is a JSON array of events for that check of that row, not a fixed pair. On an initial check with no changes, it contains an 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:
These details are in the fetched events, not in the webhook body. Without include_completions=true, completion events are hidden; established events are still returned.
Previously, monitor_id contained the row ID. Receivers using that payload must read the row ID from row_id and the parent monitor ID from monitor_id.

Whole-monitor completion

Subscribe to monitor.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:
The notification body is:
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:
URL-encode 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-Type carries the event type and Sixtyfour-Event-Id carries the row notification’s event_group_id or the whole-monitor notification’s run_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 using monitor_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.