Charchy Senddocs

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 or localhost. 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

EventWhen
email.sentOur delivery infrastructure accepted the email.
email.deliveredA recipient's mail server accepted it.
email.delivery_delayedA recipient's server is refusing for now; we keep trying.
email.bouncedA recipient's server refused it. A permanent bounce suppresses the address.
email.complainedA recipient marked it as spam. The address is suppressed.
email.failedIt couldn't be sent, e.g. your domain stopped verifying. Refunded.
email.suppressedA recipient was skipped: it's on your suppression list. Not charged.
email.expiredIt couldn't leave before its expires_at, or waited 3 days past its due time while sending was paused. Refunded.
email.canceledYou canceled it. Refunded.
domain.verifiedA sending domain is verified and ready to send from.
domain.failedA sending domain's verification failed, or a verified one lost its DKIM records.
account.pausedSending was paused for your workspace.
account.resumedSending resumed.
balance.low20% 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"
  }
}
  • id equals the webhook-id header and stays the same on every retry.
  • created_at is when the event happened; data.created_at is when the email was accepted.
  • data.test is true when the email was sent with a test key (as on GET /v1/emails/{id}). The top-level "test": true marks a sample from Send test event instead.
  • Per-recipient events add recipient.
  • email.bounced adds bounce, email.suppressed adds suppressed, email.failed adds failed and email.expired adds expired, 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:

HeaderValue
webhook-idThe event's id (evt_…). The same on every retry of that event.
webhook-timestampWhen this attempt was signed, in Unix seconds.
webhook-signaturev1,<signature> — one or more, separated by spaces.
user-agentCharchy-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:

  1. 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.
  2. Reject timestamps more than 5 minutes old (or ahead), so a captured request can't be replayed.
  3. 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 2xx means "received". 410 Gone disables 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-id and skip repeats.
  • Order is not guaranteed. email.delivered can arrive before email.sent. Order by created_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.

On this page