Webhooks
Get a signed HTTP request when an email is sent, fails, is opened or clicked. Payloads, signatures and limits.
On this page
Webhooks notify your application about email events. EmailFlare sends a signed POST to each endpoint that subscribed to the event.
Register an endpoint
Webhooks are managed by admins under Webhooks in the admin workspace.
- Enter the URL that should receive events. Use HTTPS in production.
- Choose the events to subscribe to.
- Copy the signing secret. It is shown once, when you create the webhook.
You can do the same with the session API:
POST /api/webhooks { "url": "https://app.example.com/hooks/email", "events": ["email.sent", "email.failed"] }
GET /api/webhooks
DELETE /api/webhooks/:id
Deleting a webhook disables it. Creating and disabling are recorded in the audit log.
Events
| Event | Fires when | data |
|---|---|---|
email.sent |
A live or test send was accepted, or a scheduled send was delivered. | id, to, from, subject. For scheduled sends: scheduledId, to. |
email.failed |
Delivery failed for a recipient. | id, to, from, subject |
email.opened |
A tracked message’s pixel was loaded. | token, url |
email.clicked |
A tracked link was followed. | token, url |
email.bounced |
Reserved. | You can subscribe to it, but EmailFlare does not send it yet. |
Opens and clicks only fire for sends made with track: true. See Send an email. Bounces are recorded as suppressions and update the activity log. To react to a bounce, poll the suppression list.
Payload
Every request has the same envelope.
{
"id": "Y3k1xT8mQ2wLr9aZpV0bN",
"event": "email.sent",
"created_at": "2026-03-01T09:00:02.314Z",
"data": {
"id": "G7hN2c0sQp4YtR8uLmX1a",
"to": "[email protected]",
"from": "[email protected]",
"subject": "Welcome to Acme"
}
}
These headers come with it:
Content-Type: application/json
X-EmailFlare-Event: email.sent
X-EmailFlare-Signature: 9f1c…
Verify the signature
X-EmailFlare-Signature is the hex-encoded HMAC-SHA256 of the raw request body, using the signing secret as the key. Compute it over the exact bytes you received, before parsing the JSON.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody: string, signature: string, secret: string): boolean {
const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signature);
return a.length === b.length && timingSafeEqual(a, b);
}
In a Worker, use Web Crypto:
async function verify(rawBody: string, signature: string, secret: string): Promise<boolean> {
const key = await crypto.subtle.importKey(
"raw",
new TextEncoder().encode(secret),
{ name: "HMAC", hash: "SHA-256" },
false,
["sign"],
);
const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(rawBody));
const expected = [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
return expected === signature;
}
Delivery behaviour
- Requests are sent once, without retries. If your endpoint is down, the event is lost. Reply with a
2xxquickly and do slow work after responding. - Delivery runs after the original request returns, so it never slows
POST /v1/send. - The log of every send is still in Activity logs, so you can reconcile after an outage.