Webhooks

Overview

Receive real-time notifications when email events occur. Webhooks allow your application to react immediately to opens, clicks, bounces, and unsubscribes without polling the API. Register an endpoint URL and the platform will send HTTP POST requests whenever matching events are recorded.

List Webhooks

Retrieve all registered webhook endpoints for your account, including the events each endpoint is subscribed to and its current status.

{
  "webhooks": [
    {
      "id": 1,
      "url": "https://yourapp.com/hooks/email-events",
      "events": "open,click,bounce",
      "active": true,
      "created_at": "2026-01-10T12:00:00Z"
    },
    {
      "id": 2,
      "url": "https://yourapp.com/hooks/unsubscribes",
      "events": "unsubscribe",
      "active": true,
      "created_at": "2026-02-05T09:30:00Z"
    }
  ]
}

Create Webhook

Register a new webhook endpoint. Provide the URL to receive events, a comma-separated list of event types to subscribe to, and an optional secret for HMAC signature verification.

{
  "url": "https://yourapp.com/hooks/email-events",
  "events": "open,click,bounce,unsubscribe",
  "secret": "whsec_your_secret_key_here"
}

{
  "id": 3,
  "url": "https://yourapp.com/hooks/email-events",
  "events": "open,click,bounce,unsubscribe",
  "active": true,
  "created_at": "2026-03-03T10:00:00Z"
}

Inbound Webhooks

The inbound webhook endpoint receives event payloads from external email providers (such as Resend, SendGrid, or Mailgun). Configure your provider to send event notifications to this URL and the platform will process and store them automatically.

{
  "type": "email.bounced",
  "email_id": "msg_abc123def456",
  "recipient": "invalid@example.com",
  "timestamp": "2026-03-03T08:15:00Z"
}

{
  "received": true
}

Verification

Each webhook delivery includes an HMAC signature in the X-Webhook-Signature header for verification. The signature is computed using your webhook secret and the raw request body. Always verify the signature before processing webhook payloads to ensure they originate from the platform.

import crypto from "crypto";

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Event Types

The following event types can be subscribed to when creating a webhook:

• email.open — Fired when a recipient opens an email (tracked via transparent pixel).
• email.click — Fired when a recipient clicks a tracked link in an email.
• email.bounce — Fired when an email bounces (hard or soft bounce).
• email.unsubscribe — Fired when a recipient unsubscribes via the opt-out link.

You can subscribe to any combination of events per webhook endpoint. Use comma-separated values in the events field when creating or updating a webhook.