Webhooks
Signed events to your server when an email is delivered, bounces or fails — the events, the payload, and how to verify the signature in Node, Laravel, Python and Go.
Webhooks tell your server what happened to each email. They follow the Standard Webhooks spec, so every major language has a library to verify them.
Set up an endpoint
In the dashboard, open Webhooks, add your endpoint's URL and pick the
events. Put the signing secret (whsec_…) in your server's environment as
CHARCHY_WEBHOOK_SECRET.
- The URL must be
https://, not a private network orlocalhost. We don't follow redirects. - Up to 5 endpoints per workspace.
- Send test event fires a sample of any event (marked
"test": true) to that endpoint, whichever events it subscribes to, even while it is failing — not while it is disabled. - Emails sent with a test key, and mail to the magic addresses, fire real events too — the easiest end-to-end check.
Events
| Event | When |
|---|---|
email.sent | Our delivery infrastructure accepted the email. |
email.delivered | A recipient's mail server accepted it. |
email.delivery_delayed | A recipient's server is refusing for now; we keep trying. |
email.bounced | A recipient's server refused it. A permanent bounce suppresses the address. |
email.complained | A recipient marked it as spam. The address is suppressed. |
email.failed | It couldn't be sent, e.g. your domain stopped verifying. Refunded. |
email.suppressed | A recipient was skipped: it's on your suppression list. Not charged. |
email.expired | It couldn't leave before its expires_at, or waited 3 days past its due time while sending was paused. Refunded. |
email.canceled | You canceled it. Refunded. |
domain.verified | A sending domain is verified and ready to send from. |
domain.failed | A sending domain's verification failed, or a verified one lost its DKIM records. |
account.paused | Sending was paused for your workspace. |
account.resumed | Sending resumed. |
balance.low | 20% of your emails are left since your last top-up, and again when none are. |
One event per recipient. email.delivered, email.delivery_delayed,
email.bounced, email.complained and email.suppressed name their address
in data.recipient — an email to three people sends one for each.
email.sent, email.failed, email.expired and email.canceled come once
per email. scheduled, queued and unknown send no event.
Opens and clicks are not tracked: pixels and rewritten links hurt transactional mail.
Payload
Every event has the same envelope; data describes the email.
{
"id": "evt_2b7k9x4m1q8w3n5p6r0s2t4v",
"type": "email.delivered",
"created_at": "2026-11-16T09:00:02.400Z",
"data": {
"email_id": "em_8f2k1x9q4w7m3n5p6r0s2t4v",
"from": "Darin Game <orders@daringaming.com>",
"to": ["customer@example.com"],
"subject": "Your order #4821",
"created_at": "2026-11-16T09:00:00.120Z",
"tags": { "type": "order_confirmation" },
"test": false,
"recipient": "customer@example.com"
}
}idequals thewebhook-idheader and stays the same on every retry.created_atis when the event happened;data.created_atis when the email was accepted.data.testistruewhen the email was sent with a test key (as onGET /v1/emails/{id}). The top-level"test": truemarks a sample from Send test event instead.- Per-recipient events add
recipient. email.bouncedaddsbounce,email.suppressedaddssuppressed,email.failedaddsfailedandemail.expiredaddsexpired, each saying why:
"bounce": {
"type": "permanent",
"sub_type": "no_email",
"message": "The recipient's mail server refused the email: the address does not exist.",
"diagnostic_code": "smtp; 550 5.1.1 user unknown"
}Full examples of every event: Events reference.
Payloads never carry the email's body; read more with
GET /v1/emails/{id}. A payload is at most
64 KB.
Headers
Every delivery is a POST with content-type: application/json and:
| Header | Value |
|---|---|
webhook-id | The event's id (evt_…). The same on every retry of that event. |
webhook-timestamp | When this attempt was signed, in Unix seconds. |
webhook-signature | v1,<signature> — one or more, separated by spaces. |
user-agent | Charchy-Webhooks/1.0 (+https://charchy.krd/docs/webhooks) |
The signature is the HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>,
keyed with your secret (the base64 part after whsec_), encoded in base64.
Verify every request
Anyone can POST to your URL. Before you trust a request:
- Check the signature against the raw body — the exact bytes received. Parsing and re-serialising the JSON changes the bytes, and the signature won't match.
- Reject timestamps more than 5 minutes old (or ahead), so a captured request can't be replayed.
- Compare in constant time.
The Standard Webhooks libraries do all three.
With a library
// npm install @charchy/send — Next.js Route Handler: app/api/webhooks/charchy/route.ts
import { verifyWebhook, WebhookVerificationError } from "@charchy/send"
export async function POST(request: Request) {
try {
// The raw body; the secret defaults to CHARCHY_WEBHOOK_SECRET.
const event = await verifyWebhook({ payload: await request.text(), headers: request.headers })
await enqueueCharchyEvent(event) // typed, camelCased; switch (event.type) narrows event.data
return new Response(null, { status: 204 })
} catch (error) {
if (error instanceof WebhookVerificationError) return new Response("Invalid signature", { status: 400 })
throw error
}
}With plain HMAC
import { createHmac, timingSafeEqual } from "node:crypto"
export function verifyCharchyWebhook(rawBody: string, headers: Headers, secret: string) {
const id = headers.get("webhook-id")
const timestamp = headers.get("webhook-timestamp")
const signatures = headers.get("webhook-signature")
if (!id || !timestamp || !signatures) throw new Error("Missing webhook headers")
const age = Math.abs(Date.now() / 1000 - Number(timestamp))
if (!(age <= 5 * 60)) throw new Error("Timestamp too old")
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64")
const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest()
const valid = signatures.split(" ").some((entry) => {
const [version, signature] = entry.split(",")
if (version !== "v1" || !signature) return false
const received = Buffer.from(signature, "base64")
return received.length === expected.length && timingSafeEqual(received, expected)
})
if (!valid) throw new Error("Invalid signature")
return JSON.parse(rawBody)
}In Express, use express.raw({ type: "application/json" }) on the
webhook route — express.json() hands you parsed JSON — and pass req.body
and req.headers to verifyWebhook (SDK).
Answer fast, work later
- Answer 2xx within 5 seconds. Slower is a failure and is retried.
- Do the real work after answering, from a queue or background job.
- Any
2xxmeans "received".410 Gonedisables the endpoint. Anything else is retried.
Duplicates and order
- Expect duplicates. A retry after a timeout can redeliver an event you
handled. Store each processed
webhook-idand skip repeats. - Order is not guaranteed.
email.deliveredcan arrive beforeemail.sent. Order bycreated_at, and never move an email's status backwards in your database.
Retries
A failed delivery is retried immediately, then after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours — about 28 hours in all.
- After 5 failures in a row, the endpoint is failing: new events wait in a queue. The oldest waiting event is retried on the schedule above as a probe; if it runs out of attempts it is marked failed, and the next waiting event becomes the probe 10 hours later. The first success (the probe's, or a Send test event) marks the endpoint healthy and sends the waiting events, at most 3 at a time.
- After 3 days of failing — or at once on
410 Gone— the endpoint is disabled and your workspace's owners and admins get an email. Waiting events are kept: Enable the endpoint within 3 days and they are sent. After that they are marked failed — still in the log, and Replay all failed since… sends them.
The delivery log keeps every attempt for 30 days — request, response code,
the start of your reply, and how long it took — with Replay for one event
or Replay all failed since…. Down for longer? GET /v1/emails/{id} always
has the current status.
Rotating the secret
Rotate secret starts a new secret. For the next 24 hours every event is
signed with both the old and the new one (two v1,… entries in
webhook-signature), so you can deploy the new secret without losing an
event. The libraries and the code above accept any matching signature.
Rotating again within those 24 hours drops the oldest secret: only the two newest sign.