Know the moment your mail hits the mailbox.
MailStream webhooks push real-time events to your application as mail pieces move through production, transit, and delivery. No polling, no delays, just HTTPS POST requests with signed payloads.
Events
Seven events. Full lifecycle coverage.
Subscribe to all events or pick only the ones your application needs. Each event includes the complete mail piece object so you always have full context.
Payload format
Predictable, typed JSON payloads.
Every webhook payload follows the same envelope structure. The nested data object contains the full mail piece resource at the time of the event.
Reliability
Signed, retried, and logged.
- Signature verification
- Every webhook includes an X-MailStream-Signature header containing an HMAC-SHA256 hash of the payload. Verify it against your webhook secret to confirm authenticity and prevent replay attacks.
- Automatic retries
- If your endpoint returns a non-2xx status code or times out, MailStream retries with exponential backoff, up to 5 attempts over 24 hours. Each retry includes the original event ID for deduplication.
- Endpoint management
- Add multiple webhook endpoints from the dashboard or via API. Filter events per endpoint so each service only receives the events it cares about.
- Event logs
- View a complete log of webhook deliveries in the dashboard, including payload, response status, and retry history. Debug integration issues without guessing.
Example
Handle a webhook in Node.js.
