Email Webhook the push side of event tracking

Why webhooks beat polling

The alternative is polling. You keep asking the platform's API "what happened to message X?" on a timer. That works, badly. You either poll often and burn API quota, or poll less often and learn about a bounce hours late. Webhooks invert the relationship: the platform pushes you the event the moment it happens, you stay quiet the rest of the time. Network-cheap for both sides, latency near zero.

What a payload looks like

Different platforms serialise differently, but the shape is roughly this:

POST /webhooks/sendmsg HTTP/1.1
Host: your-app.example.com
Content-Type: application/json
X-Sendmsg-Signature: sha256=...
X-Sendmsg-Event-Id: evt_01HX4...

{
  "event": "bounced",
  "event_id": "evt_01HX4...",
  "timestamp": "2026-06-30T10:14:22Z",
  "message_id": "msg_01HX3...",
  "recipient": "[email protected]",
  "bounce_type": "hard",
  "diagnostic": "550 5.1.1 mailbox unavailable"
}

Your endpoint reads the event, updates your database (suppress this address, log the bounce, notify the user), and replies with a 200. The platform marks the event delivered and moves on. If your endpoint returns 5xx or times out, the platform retries.

The gotchas that bite people

Three things every webhook receiver needs to get right. Idempotency: retries happen. The same event will arrive more than once. Use the platform's event_id as a dedup key and stop yourself from suppressing the same recipient twice. Signature verification: anyone on the internet can POST to your endpoint. The platform signs each request with a shared secret; verify the signature before trusting the payload. Async processing: don't do heavy work inline. Accept the request, queue it, return 200 fast. If your endpoint takes 30 seconds to respond, the platform will assume it failed and retry, and you'll process duplicates.

Common event types worth handling

Most teams don't need every event. The ones that earn their keep: delivered (the receiving server accepted the message), bounced (hard or soft — suppress hard, retry soft), complained (the user hit "report spam" — definitely suppress), and unsubscribed. The engagement events (opened, clicked) are noisier — opens especially are unreliable post-Apple MPP — but useful in aggregate.

Retry behaviour and failure modes

Webhook platforms retry failed deliveries with backoff. Typical schedule: immediate, then after a few minutes, then exponentially up to 24 hours, then give up. If your endpoint is down for hours, you'll get a flood of catch-up events when it comes back. Plan for that, your bounce-suppression logic should handle "this event is 6 hours old" without breaking. Most platforms also surface a recent-failures dashboard so you can replay events your endpoint dropped.

How sendmsg.io handles webhooks

Configure one or more webhook endpoints per account, with optional per-event-type filtering. Each request is signed with HMAC-SHA256 and carries a unique event_id for dedup. Failed deliveries retry on backoff, and you can replay specific events from the dashboard. The reputation engine consumes the same event stream you do, which is how it watches bounce and complaint signals in real time and adjusts per-domain sending speed.

Want to see where your sending stands today? The free deliverability check audits your SPF, DKIM, DMARC, and MX in seconds.