Webhooks

Webhooks push delivery events to your server as they happen — no polling needed.

Register a webhook

const webhook = await connect.webhook.create({
  url: "https://yourapp.com/webhooks/connect",
  secret: "whsec_your-secret-here",
  events: ["message.sent", "message.delivered", "message.failed", "message.bounced"],
  description: "Production webhook",
});

Available events

Event	Fired when
`message.sent`	Message handed off to the provider
`message.delivered`	Message confirmed delivered
`message.failed`	Delivery attempt failed
`message.bounced`	Recipient address bounced
`message.rejected`	Message rejected by the provider

Verify signatures

Every webhook request includes an X-Webhook-Signature header with an HMAC-SHA256 signature. Always verify it before processing the payload:

webhook-handler.ts

import crypto from "node:crypto";

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

Webhook payload

{
  "type": "message.delivered",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "id": "msg_...",
    "channelType": "email",
    "to": "user@example.com",
    "status": "delivered"
  }
}

Test a webhook

Send a test event to verify your endpoint is working:

await connect.webhook.test({ id: "wh_..." });

This sends a webhook.test event to the webhook URL with a signed payload.

List webhook events

Inspect the delivery log for a specific webhook:

const { items } = await connect.webhook.listEvents({
  webhookId: "wh_...",
  limit: 20,
  offset: 0,
});

Each event includes status, attempts, responseStatus, and responseBody so you can debug failures.

Manage webhooks

// Update
await connect.webhook.update({
  id: "wh_...",
  events: ["message.delivered", "message.failed"],
});

// Disable
await connect.webhook.delete({ id: "wh_..." });