Email webhooks
Email Webhooks for Delivery State
An accepted send is only the start. NoticeAPI turns provider outcomes into signed callbacks, recipient timelines, and status records your app can use when delivery changes.
POST /webhooks/noticeapi
x-noticeapi-event: email.bounced
x-noticeapi-signature: sha256=...
x-noticeapi-webhook-id: wh_...
{
"type": "email.bounced",
"messageId": "msg_...",
"recipient": "[email protected]",
"detail": "550 mailbox unavailable"
}Verify before you act
HMAC signatures cover the raw body, so handlers can reject anything that does not match the endpoint secret.
Use the same event trail
Delivery, bounce, complaint, suppression, unsubscribe, and tracking outcomes land in timelines and callbacks.
Route by endpoint id
Every enabled endpoint receives the event with x-noticeapi-webhook-id for internal routing and separation.
Test the bad paths
Simulator recipients trigger delivered, bounced, complained, and suppressed outcomes before production mail is involved.
Event pipeline
From delivery signal to product state.
Keep the callback aligned with the trail support sees: provider outcome, NoticeAPI timeline, signed payload, then your app's acknowledgement.
Verify webhook signaturesOutcome lands
Provider events become NoticeAPI delivery, bounce, complaint, suppression, unsubscribe, or tracking events.
Message state changes
The email detail page and status endpoint show the message state your webhook receives.
Payload leaves signed
Every enabled endpoint receives a raw-body HMAC signature and endpoint id with the event.
Your app acknowledges
Return a quick 2xx after verification, then move heavier work into your own queue.
How it works
Turn delivery outcomes into product logic.
Add your receivers
Create one or more HTTPS endpoints in the portal and keep each generated signing secret private.
Check the signature
Verify HMAC-SHA256 against the raw body before enqueueing work or mutating product state.
Route and dedupe
Use messageId, type, and webhookId to keep handlers idempotent across internal jobs.
Run simulator outcomes
Send to delivered@, bounced@, complained@, or [email protected] and watch the same path.
Trust
Signed events beat polling guesses.
Treat every callback as untrusted until the HMAC matches. Return a quick 2xx after the important checks, then do heavier account, billing, or support updates in your own queue.
Implementation links
Build with the shipped docs.
FAQ
Questions developers ask before switching email.
Can I connect more than one webhook endpoint?
Yes. NoticeAPI sends each event to every enabled endpoint and includes x-noticeapi-webhook-id for routing.
What should my endpoint return?
Return any 2xx quickly after verifying the signature. Process slower work asynchronously in your own app.
Should I treat webhooks as the only source of truth?
No. Webhooks are the push path. Keep handlers idempotent and use the email status endpoint or dashboard timeline when you need to reconcile a message later.
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 in the sandbox, then send from a verified domain.
Free includes simulator testing and 3,000 emails per month. Real sending on Free needs operator activation plus a verified domain; Pro adds more volume, domains, contacts, automation runs, REST attachments, and visible usage billing.