Processing bounce and complaint webhooks end to end

A bounce or complaint webhook is only useful if something happens because of it. Too many integrations log the event, maybe increment a counter, and keep emailing the same dead address or the same annoyed recipient.

Here is a complete pipeline, from the HTTP request hitting your endpoint to the account state your product shows.

What you are trying to achieve#

When a provider reports a hard bounce or a spam complaint, four things should follow:

1. Stop sending to that address, quickly and reliably, so you do not keep damaging your sender reputation.
2. Tell the product, so the user sees "we couldn't reach your email address" instead of silently missing invoices.
3. Keep a record for support and audits.
4. Alert humans when rates spike, because a sudden wave of bounces or complaints usually means something broke.

Stage 1: receive and verify#

Your webhook endpoint should do as little as possible synchronously:

@app.post("/webhooks/email")
def email_webhook(request):
    raw = request.body                      # raw bytes, before JSON parsing
    sig = request.headers.get("X-Signature-Header")
    if not verify_signature(raw, sig, WEBHOOK_SECRET):
        return Response(status=401)
    event = json.loads(raw)
    enqueue("process_email_event", event)   # durable queue, not in-memory
    return Response(status=200)

The header name and signing scheme depend on your provider. Most use an HMAC over the raw body with a shared secret. Verify against the raw bytes; parsing and re-serializing JSON changes the bytes and breaks the comparison. Use a constant-time comparison function.

Return a 2xx quickly. Providers retry when you are slow or return errors, and processing inline invites timeouts, which invite retries, which invite duplicate processing.

Stage 2: normalize and deduplicate#

In the background worker, convert the provider's payload into your own event shape and drop duplicates:

def process_email_event(event):
    normalized = {
        "provider_event_id": event["id"],
        "type": map_type(event["event"]),    # bounced, complained, delivered...
        "recipient": event["to"].strip().lower(),
        "message_id": event.get("message_id"),
        "reason": event.get("bounce_reason"),
        "occurred_at": event["timestamp"],
    }
    if not insert_event_if_new(normalized):   # unique on provider_event_id
        return                                 # duplicate delivery; already handled
    route(normalized)

Webhook systems deliver at least once, so duplicates are normal. A unique constraint on the provider's event ID is the simplest deduplication. If your provider does not supply an event ID, derive one from stable fields such as message ID, event type and timestamp.

Normalize addresses consistently. Lowercasing is generally safe for the domain part and is common practice for the whole address in suppression lists, even though the local part is technically case-sensitive.

Stage 3: route by event type#

Hard bounces#

A hard bounce means the receiving server permanently rejected the address: the mailbox does not exist, the domain does not exist, or a similar 5xx-class failure. Action:

• Add the address to your suppression list with reason hard_bounce and the SMTP response text.
• Mark the user's email as undeliverable in your product.
• Stop all future sends to it until the user updates or re-verifies the address.

Some providers suppress hard-bounced addresses automatically on their side. Keep your own suppression list anyway, so your application knows not to try, and so behavior does not change if you switch providers.

Soft bounces#

Temporary failures, such as a full mailbox or a server temporarily refusing mail, usually do not warrant suppression on the first occurrence. Track them, and suppress only after repeated soft bounces over a period of days, since a mailbox that has been "full" for two weeks is probably abandoned.

Complaints#

A complaint means the recipient marked your message as spam and their mailbox provider reported it through a feedback loop. Action:

• Suppress the address for that category of mail immediately. For marketing mail, that means unsubscribing them.
• For transactional mail, think carefully. A complaint about a password reset is often a mistake, but repeatedly sending to someone who complains is a reputation risk. Many teams suppress non-essential notifications and keep only critical account and security mail.
• Record the complaint against the template that triggered it, so product owners can see which messages generate complaints.

Unsubscribes#

If your provider handles one-click unsubscribe links and reports them as events, record them as opt-outs for the relevant category.