Definition
An email webhook is an HTTP callback that an email service provider sends to your application when a specific event occurs during the lifecycle of an email message. Webhooks replace polling by pushing event data to your server as soon as the event happens, reducing latency and eliminating unnecessary API calls. Common email webhook events include processed, delivered, opened, clicked, bounced (hard and soft), complained (spam report), dropped (rejection before sending), and deferred (temporary delivery failure).
The webhook payload is typically a JSON object containing event metadata such as the timestamp, recipient email address, event type, campaign identifier, message ID, and event-specific properties like the user agent for opens or the bounce classification code for bounces. Reliability is handled through retry mechanisms: most ESPs retry failed webhook deliveries with exponential backoff for up to 72 hours before dropping the event. Webhook endpoints must return a 2xx HTTP status code within a few seconds to acknowledge receipt; otherwise the delivery is considered failed and retried.
Best Practices
Design your webhook handler to be idempotent. Network interruptions can cause duplicate webhook deliveries even when the original delivery succeeded. Your handler should detect and discard duplicate events using the unique event ID provided in the payload.
Return a 200 OK or 202 Accepted status code within three seconds of receiving the webhook. Slow responses cause retries and may lead to your endpoint being considered unreliable. If processing takes longer, acknowledge the webhook immediately and process the event asynchronously using a queue.
Store raw webhook payloads in a database or log for debugging. When investigating delivery anomalies, having the original event data allows you to trace exactly what the ESP sent and when. Include the webhook event ID, timestamp, and recipient in your application logs.
Implement a health-check endpoint for webhook verification. Many ESPs send a GET request to your webhook URL during setup to verify the endpoint is active. Your endpoint should respond with a 200 OK without requiring authentication for these verification requests.
Monitor webhook delivery failure rates. If your endpoint becomes unavailable or slow, webhooks will be retried and eventually dropped. Set up alerting for high webhook failure rates so you can address infrastructure issues before event data is lost.
Related Glossary Terms
Back-in-Stock
Back-in-stock email alerts notify waiting subscribers when inventory returns. Conversion rates reach 25–40% for well-timed alerts with urgency and exclusivity messaging.
Email Lifecycle
Email lifecycle marketing uses automated, behavior-triggered emails that align with each stage of the customer journey.
Email Subscriber Health
Email subscriber health scoring combines recency, frequency, engagement depth, and complaint history into a composite metric. Health scores enable automated treatment decisions and deliverability protection.
Onboarding Sequence
An onboarding sequence is a series of automated emails that welcome new subscribers and guide them through their first interactions with your brand.
Price Drop
Price drop and sale alert emails notify subscribers when monitored products decrease in price. Dynamic tracking enables personalised notifications at configurable thresholds.
Replenishment
Replenishment or refill reminder emails automatically notify subscribers when consumable products need reordering based on purchase date and usage cycle.
Frequently Asked Questions
Polling requires your application to repeatedly call an API to check for new events, which introduces latency and consumes API quota even when no events exist. Webhooks push events to your application immediately when they occur, providing real-time data with lower overhead and no polling delay.
When a webhook delivery fails (non-2xx response or timeout), the ESP typically retries the delivery with exponential backoff starting at one minute and increasing up to several hours. Total retry windows vary by provider but are usually between 24 and 72 hours. After the retry window expires, the event is dropped.
At minimum, subscribe to bounced, complained, and dropped events to track list health and sending reputation. Add delivered and deferred events for delivery rate visibility. Add opened and clicked events for engagement tracking. The optimal set depends on your use case and desired level of granularity.
Yes, webhooks are designed for high-volume event delivery. ESPs batch events and send them as arrays of JSON objects, with each batch containing multiple events. Batching reduces HTTP overhead while maintaining real-time delivery. Your endpoint must be able to process batches of varying sizes efficiently.
Webhook URLs should use HTTPS to encrypt the payload in transit. Many ESPs also support signature verification, where each webhook request includes a cryptographic signature in the header that you can verify to confirm the request originated from the ESP and was not tampered with.