Why aren't my bounce webhooks working?

Bounce webhooks usually fail for one of a few common reasons. Here’s a quick checklist to narrow it down:

1) The webhook endpoint isn’t publicly reachable

Your bounce URL must be accessible from the internet over HTTPS. Common problems:

• localhost / private IP
• firewall or IP allowlist blocking the provider
• DNS not resolving correctly
• SSL certificate issues

2) Your endpoint doesn’t return a fast 2xx response

Most email providers expect your webhook to respond quickly with 200 OK (or another 2xx). If it times out, returns 301/302, 4xx, or 5xx, delivery may fail.

3) The webhook URL is incorrect

Double-check:

• exact path
• trailing slash
• query string
• environment mismatch (test vs prod)

4) The webhook payload is being rejected

Your server may be receiving the request, but:

• JSON parsing fails
• required headers are missing
• signature verification fails
• body size limit is too small

Check your app logs for 400/401/403 responses.

5) Event type isn’t actually configured

Some services separate:

• delivery events
• bounce events
• complaint/spam events
• bounce classifications

Make sure bounce notifications are enabled for the sending domain/configuration.

6) Your provider requires webhook verification

Some systems require an initial verification handshake or signature validation. If you don’t complete it, the webhook won’t be activated.

7) You’re testing with messages that don’t generate bounces

Not every failed email becomes a bounce webhook. For example:

• invalid recipient formats
• suppressed addresses
• blocked sends
• deferred/retried messages

May produce different events instead of a bounce.

8) Webhook secret/signature mismatch

If you verify signatures, confirm:

• correct secret key
• correct raw request body used for verification
• timestamp tolerance not too strict
• matching algorithm/version

9) Retries are happening, but you’re not seeing them

Providers often retry failed webhooks. Look for repeated attempts in logs. If you acknowledge but then error internally, the provider may consider it delivered.

---

Best next debugging steps

1. Check the provider’s event log for bounce attempts.
2. Check your server/access logs for incoming requests.
3. Confirm the endpoint returns 200 within a few seconds.
4. Temporarily log the raw request body and headers.
5. Test with a simple public endpoint (e.g. requestbin/webhook.site) to confirm the provider is sending anything at all.

If you want, paste:

• the email provider you’re using
• your webhook route code
• one example webhook attempt/error from logs

…and I can help you pinpoint the issue quickly.