How do I handle bounce webhooks?

To handle bounce webhooks, you generally want to:

1. Receive the webhook

   • Expose an HTTPS endpoint that accepts POST requests.
   • Verify the webhook signature if your provider supports it.

2. Parse the event

   • Identify which email address and message ID bounced.
   • Determine whether it’s a hard bounce (permanent failure) or soft bounce (temporary failure).
   • Capture any provider-specific reason codes or diagnostic text.

3. Update your records

   • Mark the recipient as undeliverable, suppressed, or “bounced.”
   • For soft bounces, you may retry or wait for repeated failures before suppressing.
   • Store the bounce details for auditing and support.

4. Stop future sends

   • Add hard-bounced addresses to a suppression list.
   • Prevent automated campaigns from sending to addresses that have bounced too many times.

5. Acknowledge quickly

   • Return a 2xx response promptly so the provider doesn’t retry the webhook unnecessarily.
   • Do any heavy processing asynchronously if possible.

6. Make handling idempotent

   • Webhooks can be delivered more than once, so deduplicate using the event ID or message ID plus recipient.

Example flow:

• Webhook arrives with event = "bounce".
• You validate the signature.
• You extract email, bounce_type, reason, message_id.
• If bounce_type == "hard", mark email as suppressed.
• If bounce_type == "soft", increment bounce count and decide whether to retry or suppress.
• Log the event and return 200 OK.

If you want, I can also give you:

• a generic webhook handler example,
• examples for SendGrid/Mailgun/SES/Postmark, or
• a database schema for bounce tracking.