Webhooks, duplicates & cancelling

Configuring a webhook

Set channels.webhookUrl when you create the monitor (POST /v1/monitors); email delivery is channels.email. The URL must be https on a public host. Put a secret token in the URL and verify it on receipt.

{ "product": "sex-offender", "type": "person", "label": "Jordan Rivera — resident 48213",
  "person": { "firstName": "Jordan", "lastName": "Rivera", "dob": "1988-04-12" },
  "channels": { "webhookUrl": "https://example.com/hooks/offendersearch?token=YOUR_SECRET" } }

Delivery and retries

• Monitors are evaluated once a day. Each alert is delivered once per channel: one POST with type: "monitor.alert" and the alert body.
• If neither email nor webhook succeeded, the alert stays pending and both are tried again on the next run, the following day. There is no faster retry schedule.
• X-Offendersearch-Signature: sha256=<hex> is the HMAC-SHA256 of the raw body when a signing secret is configured; deliveries are not signed today and no secret is issued, so authenticate with the token in your URL and read the alert back from GET /v1/monitors/{monitorId}/alerts when you need certainty. Delivery carries the current status.

Duplicate alerts

• Key your processing on the alert's id; a redelivery after a failed run carries the same id.
• An alert names its event (new, changed, removed) and the record (personRef, and externalId for criminal records). The same record changing twice produces two alerts with different ids.
• Alert history is the source of truth: GET /v1/monitors/{monitorId}/alerts returns every alert whatever happened to its delivery (newest first, up to 200).

Cancelling

DELETE /v1/monitors/{monitorId} cancels a monitor: evaluation stops now and it is not charged on any invoice prepared after the cancel (monitors are billed flat per active monitor, $3 person or $10 location, counted at invoice time; there is no proration). Its alerts stay readable. Cancelling twice is harmless. See Billing.

Related

• Delivery
• Alerts
• Monitoring API reference