Skip to main content

Use case

Get told when a monitored field changes or a check fails, instead of polling. A monitor posts a small notification to your webhook after each check of each row, and your receiver reads the full events 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. A monitor sends only the event types you list. With no event types it sends nothing, even when webhook_url is set. Checks that are skipped send no 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. Event types are set at creation.
A monitor with many rows sends one notification per row per check. Subscribe to monitor.execution.completed only if you need a signal for every quiet check.

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. One check records at most one change event per watched field, so a limit of 500 returns every event from a check unless the monitor watches more than 500 fields. The events endpoint needs the monitor ID as well as the row ID. Store each row ID from the create response against its monitor ID, as the example below does.

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 event_group_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

Create the monitor and save which monitor each row belongs to. The example uses SQLite, which handles concurrent writers and gives the receiver a keyed lookup; use your own database the same way.
Python
Then verify each notification against the raw body, look up its monitor, and read the check’s events. verify is the function from Signing Secrets & Verification. The receiver looks each row up in the database, so monitors created after it starts are picked up.
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.