Skip to Content
Docs
Guides

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:

  1. Navigate to Webhooks and click Add endpoint.
  2. Provide your public HTTPS endpoint URL (e.g. https://api.yourdomain.com/webhooks/emitd).
  3. Select which event types to receive.
  4. Click Create endpoint.
  5. Copy the displayed Signing Secret (whsec_...) immediately. It is shown in full exactly once.

The Add webhook endpoint panel: an endpoint URL and a checklist of events


Supported event types & delivery lifecycle

emitd maps every stage of an email's life to distinct event topics:

GroupEvent NameWhen it triggers
Delivery lifecyclesentAmazon SES has accepted the message from the emitd edge queue.
deliveryThe destination mailbox provider (e.g., Gmail, Outlook) accepted the message for delivery.
delivery_delayedThe destination mail server temporarily deferred delivery (greylisting or recipient inbox full). Delivery will be retried automatically by SES.
failedThe message could not be dispatched due to an unrecoverable edge or SES error.
Reputation & List HygienebounceHard bounce (e.g., mailbox does not exist or domain rejects mail). The address is automatically added to your suppression list.
complaintRecipient clicked "Mark as Spam". The address is immediately suppressed across your account.
suppressedA send attempt was dropped because the recipient is already on your suppression registry.
EngagementopenRecipient rendered the email (triggered by the 1x1 tracking pixel).
clickRecipient clicked a tracked hyperlink in the email body.
Scheduled SendsscheduledA message was accepted with a future scheduled_at timestamp.
cancelledA previously scheduled email was cancelled before dispatch.
Audience & Inboundcontact.createdNew contact added to an audience list.
contact.updatedContact tags or attributes updated.
contact.deletedContact removed from an audience.
inbound.receivedInbound email parsed and structured at the edge. See Inbound guide.

Event payload shape

All webhooks POST a JSON body with the following structure:

POST https://your-domain.com/webhooks/emitd
{
  "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: 1783386190864

Compute the HMAC-SHA256 hash over the raw request body bytes using your webhook secret, and perform a constant-time comparison against the header.

webhook-handler.ts
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 2xx response within 5 seconds. Any status outside 200–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

On this page