Webhooks
Real-time signed delivery reports, HMAC-SHA256 signature verification in Node.js, Python, Go, and PHP, and automated retry policies.
emitd delivers real-time HTTP POST notifications to your endpoints at every stage of a message's lifecycle — from edge acceptance and mailbox delivery to opens, clicks, bounces, and spam complaints.
Every payload is cryptographically signed using HMAC-SHA256 so you can verify authenticity before processing.
Subscribing to webhooks
You can configure webhook subscriptions in the Console or programmatically via POST /v1/webhooks.
In the Console:
- Navigate to Webhooks and click Add endpoint.
- Provide your public HTTPS endpoint URL (e.g.
https://api.yourdomain.com/webhooks/emitd). - Select which event types to receive.
- Click Create endpoint.
- Copy the displayed Signing Secret (
whsec_...) immediately. It is shown in full exactly once.

Supported event types & delivery lifecycle
emitd maps every stage of an email's life to distinct event topics:
| Group | Event Name | When it triggers |
|---|---|---|
| Delivery lifecycle | sent | Amazon SES has accepted the message from the emitd edge queue. |
delivery | The destination mailbox provider (e.g., Gmail, Outlook) accepted the message for delivery. | |
delivery_delayed | The destination mail server temporarily deferred delivery (greylisting or recipient inbox full). Delivery will be retried automatically by SES. | |
failed | The message could not be dispatched due to an unrecoverable edge or SES error. | |
| Reputation & List Hygiene | bounce | Hard bounce (e.g., mailbox does not exist or domain rejects mail). The address is automatically added to your suppression list. |
complaint | Recipient clicked "Mark as Spam". The address is immediately suppressed across your account. | |
suppressed | A send attempt was dropped because the recipient is already on your suppression registry. | |
| Engagement | open | Recipient rendered the email (triggered by the 1x1 tracking pixel). |
click | Recipient clicked a tracked hyperlink in the email body. | |
| Scheduled Sends | scheduled | A message was accepted with a future scheduled_at timestamp. |
cancelled | A previously scheduled email was cancelled before dispatch. | |
| Audience & Inbound | contact.created | New contact added to an audience list. |
contact.updated | Contact tags or attributes updated. | |
contact.deleted | Contact removed from an audience. | |
inbound.received | Inbound email parsed and structured at the edge. See Inbound guide. |
Event payload shape
All webhooks POST a JSON body with the following structure:
{
"id": "evt_9b7Fc1Kp8Lm",
"type": "bounce",
"created_at": 1783386190864,
"data": {
"message_id": "msg_2h8Kd0Rk9Qa",
"ses_message_id": "0100018f992a7e4b-91c2b5d4-e6f7-4a8b-9d1e-2f3a4b5c6d7e-000000",
"from": "Acme <hello@yourdomain.com>",
"to": ["invalid-user@example.com"],
"subject": "Welcome to our platform!",
"bounce_type": "Permanent",
"bounce_sub_type": "General",
"diagnostic_code": "smtp; 550 5.1.1 <invalid-user@example.com>: Recipient address rejected",
"tags": {
"campaign": "welcome-flow"
}
}
}Verifying HMAC-SHA256 signatures
To guarantee that requests originate from emitd and haven't been tampered with in transit, every delivery carries an X-Webhook-Signature header:
X-Webhook-Signature: sha256=a1b2c3d4e5f6...
X-Webhook-ID: evt_9b7Fc1Kp8Lm
X-Webhook-Timestamp: 1783386190864Compute the HMAC-SHA256 hash over the raw request body bytes using your webhook secret, and perform a constant-time comparison against the header.
import crypto from "node:crypto";
import type { IncomingMessage, ServerResponse } from "node:http";
const WEBHOOK_SECRET = process.env.EMITD_WEBHOOK_SECRET!;
export function verifyWebhookSignature(
rawBody: Buffer,
signatureHeader: string,
secret: string
): boolean {
if (!signatureHeader || !signatureHeader.startsWith("sha256=")) {
return false;
}
const expectedHash = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
const expectedSignature = `sha256=${expectedHash}`;
// Constant-time comparison prevents timing attacks
return crypto.timingSafeEqual(
Buffer.from(signatureHeader),
Buffer.from(expectedSignature)
);
}Always verify against raw bytes
Do not parse or format JSON before verifying signatures. Frameworks that mutate whitespace or re-order object keys will cause HMAC hash comparison to fail. Always capture the raw byte buffer before passing it to verification functions.
Delivery retries & failure policy
- Response requirement: Your handler must return an HTTP
2xxresponse within 5 seconds. Any status outside200–299(or a connection timeout) is logged as a delivery failure. - Exponential backoff: Failed webhook deliveries are retried automatically with progressive delays:
- 1st retry: 1 minute
- 2nd retry: 5 minutes
- 3rd retry: 30 minutes
- 4th retry: 2 hours
- Retries 5 through 8: every 8 hours
- Maximum attempts: After 8 total attempts, the delivery is transitioned to
failed. - Manual replay: If your server experiences an outage or deployment interruption, you can replay individual events or re-dispatch all failed events from the past 7 days via the Console or by calling
POST /v1/webhooks/{id}/replay.
Endpoint health
Console → Webhooks shows the delivery rate of each endpoint's latest 200 deliveries. A new endpoint gets a test event as soon as you add it, so a wrong URL shows up straight away.
An endpoint counts as failing when, over 6 hours, at least 5 deliveries failed and more failed than succeeded.
- After an hour of failing, workspace owners and admins get an email with the endpoint's latest response.
- After 24 hours of failing, emitd pauses the endpoint and emails them again. Sending isn't affected.
- While it's paused, events aren't delivered to it, and they aren't delivered later either. Failed events from before the pause stay in its history for 30 days, and you can redeliver them.
To turn a paused endpoint back on, fix it and resume it from the Webhooks page. Resuming or changing its URL starts the health check again.
Next steps
API Recipes & Code Patterns
Explore end-to-end inbound and delivery webhook implementations.
Webhook events reference
Full JSON schema definitions for all 16 supported event payloads.
Test mode & sandbox
Simulate delivery, bounce, and complaint webhooks without sending live emails.
Suppression list
Understand how bounces and spam complaints protect your sending reputation.