Verify before you act
The HMAC covers the raw request body, so your handler can reject anything that does not match the endpoint's signing secret.
Accepted is not delivered. Catch every outcome that follows.
The real outcome — delivered, bounced, complained — lands after your send already returned 200. NoticeAPI pushes each one as a signed callback and keeps the same trail in the recipient timeline and status API for when you need to reconcile.
- 1Register your endpointsAdd one or more HTTPS receivers in the portal and keep each generated signing secret private.
- 2Check the signatureVerify HMAC-SHA256 against the raw body before enqueueing work or mutating product state.
- 3Route and dedupeUse messageId, type, and webhookId so a repeated event cannot run the same internal job twice.
- 4Run simulator outcomesSend to delivered@, bounced@, complained@, or [email protected] and watch the same path.
Turn delivery outcomes into product logic.
- 1
Register your endpoints
Add one or more HTTPS receivers in the portal and keep each generated signing secret private.
- 2
Check the signature
Verify HMAC-SHA256 against the raw body before enqueueing work or mutating product state.
- 3
Route and dedupe
Use messageId, type, and webhookId so a repeated event cannot run the same internal job twice.
- 4
Run simulator outcomes
Send to delivered@, bounced@, complained@, or [email protected] and watch the same path.
One outcome, four checkpoints your app can trust.
Your webhook carries the same trail support reads: provider outcome, NoticeAPI timeline, signed payload, then your app's acknowledgement.
Verify webhook signaturesProvider
Outcome lands
Provider events become NoticeAPI delivery, bounce, complaint, suppression, unsubscribe, or tracking events.
Timeline
Message state changes
The email detail page and status endpoint show the message state your webhook receives.
Signature
Payload leaves signed
Every enabled endpoint receives a raw-body HMAC signature and endpoint id with the event.
Ack
Your app acknowledges
Return a quick 2xx after verification, then move heavier work into your own queue.
The controls around the path.
One trail, read three ways
The same delivered, bounced, complained, suppressed, and unsubscribed events reach your webhook, the recipient timeline, and the status API.
Route by endpoint id
x-noticeapi-webhook-id tags every event, so several endpoints can split traffic by service without guessing.
Rehearse the failures
Simulator recipients fire delivered, bounced, complained, and suppressed outcomes down the same path before any real mailbox is involved.
Verify first, respond fast, reconcile later.
Treat every callback as untrusted until the signature matches. Return 2xx as soon as the checks pass, then push heavier account, billing, or support work onto your own queue.
Read the implementation.
Questions before you ship.
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?
Pair the push with a pull. Webhooks deliver events as they happen; the email status endpoint and dashboard timeline let you re-read any message, and stored event ids keep repeated callbacks from running the same work twice.
Can I test webhooks without sending real email?
Yes. Simulator recipients exercise the same event and webhook pipeline without real mailboxes or quota use.
Test it. Then send for real.
Simulator outcomes are free. Move to a verified domain when the path is ready.