Alert Webhooks

Alert Webhooks

Have each new alert POSTed to a URL you control, for example a ticketing system, a chat tool or an automation platform.

Setting Up

1. Go to Settings → API Access and save your endpoint under Webhook URL.
2. Go to Monitoring → Alerts → Configure, open the alert configuration you want delivered, and tick the Webhook notification channel.
3. Return a 2xx status from your endpoint. Anything else is recorded as a failed delivery.

Request

One POST per alert, JSON body, 10 second timeout, with two headers you can route on before parsing the body:

• X-Alert-Type — the alert sub-type, e.g. spf_record_missing
• X-Alert-Severity — critical, warning or info

Payload

{
  "alert_id": 12345,
  "type": "spf_record_missing",
  "category": "configuration",
  "severity": "critical",
  "title": "SPF Record Missing",
  "message": "No SPF record was found for example.com",
  "domain": { "id": 678, "name": "example.com" },
  "details": { ... },
  "triggered_at": "2026-10-22T04:30:00+00:00"
}

Securing Your Endpoint

Payloads are not yet signed. Treat the webhook URL itself as a secret: include an unguessable path segment or query token, serve it over HTTPS, and reject requests that do not carry it. You can confirm any alert independently with GET /api/v1/alerts/{id} before acting on it.

Delivery

• Delivery is attempted once. Failed deliveries are visible in the alert’s notification history and are not retried automatically.
• Only alerts are delivered today. Domain verification, SPF activation and DMARC policy changes are not yet webhook events; poll GET /api/v1/domains/{name}/status for those.

Planned

Signed payloads (HMAC SHA-256 with a per-account secret), automatic retries with backoff, and additional event types are planned. This page will be updated when they ship; nothing above will stop working.