Webhooks

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

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.opened`	Open tracked (when tracking enabled)
`email.clicked`	Link click tracked
`email.unsubscribed`	Broadcast recipient unsubscribed

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. Retries and multiple endpoints are on the roadmap — design your handler to be idempotent on messageId + type.