Using Corsair
Event hooks
Corsair POSTs a JSON payload to an endpoint you choose when something happens. Add one under Webhooks in the control panel.
Verifying a delivery#
Every delivery is signed. Verify it. Without the check, anyone who learns your URL can post whatever they like and your system will believe it.
The scheme is Standard Webhooks, so the libraries you may already have work unchanged. Three headers:
| Header | Meaning |
|---|---|
webhook-id |
Unique per delivery. Store it to deduplicate retries. |
webhook-timestamp |
Unix seconds. Reject anything more than a few minutes old. |
webhook-signature |
v1,<base64> — HMAC-SHA256 over id.timestamp.body |
The svix-id, svix-timestamp, and svix-signature aliases carry the same values, for tooling that expects those names.
import { createHmac, timingSafeEqual } from "node:crypto"
const verify = (secret, headers, body) => {
const id = headers["webhook-id"]
const timestamp = headers["webhook-timestamp"]
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64")
const expected =
"v1," + createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64")
return headers["webhook-signature"]
.split(" ")
.some((candidate) => {
const a = Buffer.from(expected)
const b = Buffer.from(candidate)
return a.length === b.length && timingSafeEqual(a, b)
})
}Sign over the raw request body, exactly as received. Parsing the JSON and re-serialising it changes the bytes and the signature will not match.
Events#
| Event | When |
|---|---|
message.received |
A message was accepted and delivered to a mailbox |
message.spam |
Accepted, but scored as spam and filed in Junk |
message.rejected |
Refused at SMTP time — no such user, over quota, filtered |
message.sent |
Accepted from one of your mailboxes for delivery |
message.delivered |
The receiving server accepted it |
message.deferred |
Temporarily refused; Corsair will retry |
message.bounced |
Permanently failed, or retries ran out |
email.scheduled · email.sent · email.delivered · email.delivery_delayed |
A sending API email on its way |
email.bounced · email.complained · email.failed · email.suppressed |
A sending API email that did not arrive |
address.created · address.deleted · address.password_changed |
Mailbox changes |
address.forwarding_changed |
A mailbox's forwarding was set through the forwarding API |
admin.granted · admin.revoked |
Someone was given, or lost, administration of a domain or of the server |
domain.created · domain.verified · domain.verification_failed · domain.deleted |
Domain changes |
quota.warning · quota.exceeded |
The account crossed 90% of its storage, or filled it |
transfer.completed · transfer.failed |
Mailbox migration |
Mail from a mailbox reports as message.; mail sent over the sending API reports as email. instead, never both.
Subscribe to exact types, a family with message., or everything with . A family wildcard is usually what you want — it picks up new event types in that family without you changing anything.
Payload#
{
"type": "message.received",
"created_at": "2026-08-10T12:00:00.000Z",
"data": {
"recipient": "[email protected]",
"sender": "[email protected]",
"subject": "Hello",
"message_id": "<[email protected]>",
"size": 4821,
"spam_score": 1.5,
"authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass" },
"remote_ip": "203.0.113.9"
}
}Every message.* event describes one recipient. A message sent to three people is three message.sent events, then three message.delivered (or deferred, or bounced) as each receiving server answers. message.sent fires for mail sent over SMTP submission, from the webmail, over JMAP, and by an agent mailbox; it does not fire for mail Corsair forwards on someone's behalf.
quota. and transfer. carry their own fields:
{ "type": "quota.warning",
"data": { "bytes_used": 9663676416, "storage_bytes": 10737418240, "percent": 90 } }
{ "type": "transfer.completed",
"data": { "transfer_id": "…", "address": "[email protected]", "server": "imap.old-host.com",
"username": "[email protected]", "messages": 18234, "bytes": 2147483648 } }A transfer.failed has error in place of messages and bytes. The quota events fire once per crossing, on the way up: an account that sits at 95% is warned once, not at every delivery. Freeing space resets it, so the next climb is announced again. The same crossing sends the account's owner an email unless they turned storage warnings off under Account.
Retries#
Answer with any 2xx and quickly — the body is ignored. Anything else is retried after 5s, 30s, 5m, 30m, 2h, 5h, 10h, and 24h, then given up on.
Retries reuse the same webhook-id, so a receiver that records the id can tell a retry from a new event. Corsair guarantees at least once, not exactly once: your endpoint should be idempotent.
An endpoint that fails twenty times in a row is disabled automatically, and the panel says so. Re-enable it once it is fixed.
Endpoint requirements#
The URL has to be reachable from the public internet. Private, loopback, and link-local addresses are refused, because the URL is customer-supplied and this server is what fetches it — an open one is a server-side request forgery.
The check is on what the host name resolves to, not how the URL is spelled, and it is made again at every delivery: a public name that points at an internal address is refused, and so is every way of writing one ([::ffff:127.0.0.1], the cloud metadata address, carrier-grade NAT). A redirect is not followed — it is treated as a failed delivery, so an endpoint that moves has to be updated here.
A self-hoster whose consumers are on the same private network can set WEBHOOK_ALLOW_PRIVATE=true.
Use the Send test button after adding an endpoint. It delivers a signed sample synchronously and shows you the status that came back and how long it took. The response body is deliberately not kept or shown — it was a way to read what an internal address answered with.