Webhooks

Configure an HTTPS endpoint in the portal and we push delivery events as they happen with no polling. Payloads are signed with your webhook secret using HMAC-SHA256 over the raw body.

The email sandbox simulator can fire delivery, bounce, complaint, and suppression events before production sending. For the product overview, read the email webhooks guide. For the broader security overview, read NoticeAPI security and data practices.

Event types

`email.delivered`	Mailbox accepted the message
`email.bounced`	Hard bounce; recipient auto-suppressed
`email.filteredspam`	Marked as spam; auto-suppressed
`email.suppressed`	Provider-level suppression
`email.quarantined`	Quarantined by the receiving server
`email.unsubscribed`	Broadcast recipient unsubscribed
`email.received`	Inbound message accepted for a verified receiving domain

Payload

delivery

POST https://yourapp.com/webhooks/email
x-noticeapi-event: email.bounced
x-noticeapi-signature: sha256=8f3a...

{
  "type": "email.bounced",
  "messageId": "0f83...",
  "recipient": "[email protected]",
  "timestamp": "2026-07-02T18:04:14.000Z",
  "detail": "550 5.1.1 mailbox unavailable",
  "accountId": "..."
}

Verify signatures

Always verify x-noticeapi-signature before trusting a payload. Your signing secret is shown on the Webhooks page.

verify.ts

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyNoticeSignature(rawBody: string, header: string, secret: string) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header);
  return a.length === b.length && timingSafeEqual(a, b);
}

Delivery semantics

Events are sent with a 5-second timeout. Respond with any 2xx quickly and process async. Multiple endpoints can be configured from the portal; design each handler to be idempotent on messageId + type.