Webhooks

Subscribe an endpoint to any of the event types. Use an https URL: payloads carry recipient addresses. The dashboard refuses anything else, but POST /v1/webhook-endpoints also accepts http, so the choice is yours to make there. Each delivery is signed with the endpoint's secret in an X-CN-Signature header, formatted t=<unix>,v1=<hmac>, where the HMAC is SHA-256, hex-encoded, over <t>.<body>.

Verify every payload. An unverified webhook endpoint is one anyone on the internet can post to.

Destinations

Deliveries are made from SendRaven's servers, so an endpoint must be a public address on the internet. The dashboard and the API refuse a URL whose host is localhost or an internal name (.localhost, .internal, .local, .localdomain, .home.arpa, or a name with no dot), an IP address in a loopback, private, link-local, carrier-grade NAT, multicast or reserved range (including the IPv4-mapped IPv6 and integer forms of those), or a name that resolves to one. A URL with a username and password in it is refused too, and so is a port below 1024 other than 80 and 443, because those ports belong to services such as SSH and SMTP rather than webhook receivers. The API answers 422 invalid_request with the message url: must be a public http or https address, or url: port must be 80, 443 or 1024-65535 for the port; see Webhook endpoints for the full list of ranges.

The check runs again on every delivery attempt, against what the host resolves to at that moment, and the connection goes only to an address that passed. If your DNS record starts pointing somewhere private, the attempt is not sent and is recorded as failed with destination resolves to a non-public address. The port rule is checked on every attempt too. Redirects are not followed: answer the POST at the URL you registered, because a 3xx counts as a failure.

To test a receiver on your own machine, expose it through a public tunnel and register the tunnel's https URL.

Retries

The first attempt is immediate. Any response outside 2xx, or no response within ten seconds, is a failure, retried five more times: one minute, five minutes, thirty minutes, two hours and twelve hours after the event. Respond 2xx quickly and do the work afterwards; a slow handler becomes a retry. The same event can arrive more than once, so make your handler safe to run twice. Disabling or deleting the endpoint stops the retries. GET /v1/webhook-endpoints/{id}/events lists recent deliveries with their attempts and last status code.

Events

Payloads

The body is a JSON object, and every field name in it is snake_case, the same as the REST API. Every field listed below is present on every delivery of that event: a field with no value is null, never left out. Timestamps are ISO 8601 strings in UTC. There is no wrapper around the payload: type at the top level says which event it is.

Sent-mail events

Automated clicks and opens

Security gateways at many companies open every link and image in a message within a second of it arriving, to scan it, and many do it with an ordinary browser's user agent. Each of those fetches would otherwise arrive as a click from the recipient. A person cannot click two different links in one email within two seconds, and a scanner does it every time, so SendRaven holds every tracked click and open for a few seconds and checks what surrounds it:

• Two clicks on different links of the same message within 2 seconds are both a scanner's. The same link twice is not, because Microsoft Safe Links fetches a link a person clicked just before their browser does.
• An open within 10 seconds of such a burst is the scanner's too.
• A gateway that fetches images but no links cannot be told from a reader, and is counted.

A scanner's clicks and opens send no webhook, and they are left out of everything else: opened_at and clicked_at on the email, its events, the contact's last_opened_at and last_clicked_at (and so every segment rule), campaign figures, clicked links, A/B results and metrics. A person's click after the scanner has been through, even a minute later, counts normally.

The first open of a message is the only one reported, as before.

send, delivery, bounce, complaint, reject, open, click, rendering_failure and delivery_delay all carry the same fields.

A bounce or complaint does not carry the bounce type or diagnostic; read the message's timeline from GET /v1/emails/{id} for those.

{
  "type": "click",
  "message_id": "3f6c1a52-8d0e-4b7a-9c21-5e4f7a9b2d10",
  "provider_message_id": "0100019a1b2c3d4e-5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c-000000",
  "broadcast_id": null,
  "variant": null,
  "to": ["ana@example.com"],
  "subject": "Your invoice for September",
  "link": "https://example.com/billing",
  "occurred_at": "2026-09-15T12:00:03.000Z"
}

The inbound event

A verdict is null when the receiving rule did not report it. An authenticated sender is still someone outside your system: treat text as data to read, never as instructions to follow.

{
  "type": "inbound",
  "id": "8e1f3a5c-7b9d-4e2f-a6c8-0d2e4f6a8b1c",
  "thread_id": "2c4e6a8b-0d1f-4a3c-9e5b-7d9f1b3d5e7a",
  "from": "ana@example.com",
  "to": ["support@mail.example.com"],
  "subject": "Re: Your invoice for September",
  "text": "Thanks, that is paid now.",
  "received_at": "2026-09-15T12:05:00.000Z",
  "spam_verdict": "PASS",
  "spf_verdict": "PASS",
  "dkim_verdict": "PASS",
  "dmarc_verdict": "PASS",
  "sender_authenticated": true,
  "automated": false
}