Email webhooks
Email Webhooks for Delivery, Bounce, and Complaint Events
NoticeAPI email webhooks push delivery outcomes back into your app so you can update product state, stop retrying bad recipients, and keep support timelines accurate without polling every send.
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);
}Signed event callbacks
Webhook payloads include x-noticeapi-signature so your app can verify the raw body before trusting it.
Delivery and failure events
Handle delivered, bounced, complaint, suppressed, quarantined, failed, and unsubscribe outcomes.
Simulator round-trip
Use simulator recipients to fire webhook paths before sending real production mail.
Suppression-aware
Bounce and complaint events can create suppressions automatically, protecting future sends.
How it works
From test send to production traffic.
Configure your endpoint
Add one HTTPS receiver in the portal and keep the signing secret private.
Verify the signature
Compute HMAC-SHA256 over the raw body and compare it to x-noticeapi-signature.
Process quickly
Return a 2xx response quickly and move heavier work into your own queue.
Test with simulator events
Send to delivered@, bounced@, complained@, or [email protected] and watch your handler.
Trust
Webhook payloads should be verified before use
Treat webhook bodies as untrusted until the HMAC signature matches your webhook secret. The simulator gives you a safe way to test that verification and event handling before production traffic.
Implementation links
Build with the shipped docs.
FAQ
Questions developers ask before switching email.
How many webhook endpoints can I configure?
One endpoint today. Design the receiver to fan out internally if multiple systems need the same event.
What should my endpoint return?
Return any 2xx quickly after verifying the signature. Process slower work asynchronously in your own app.
Can I test webhooks without sending real email?
Yes. Simulator recipients exercise the same event and webhook pipeline without real mailboxes or quota use.
Start free. Send production after your domain is ready.
Free includes 3,000 production emails per month, a 100/day production cap, and one verified sending domain.