Handling bounces and complaints automatically with webhooks
A webhook is a message your sending platform pushes to your own system as soon as something happens to an email: delivered, bounced, reported as spam, opened. By responding to it, you handle bounces and complaints automatically: a hard-bounced address is blocked in your CRM straight away, a complaint becomes an unsubscribe, a soft bounce is counted. Without webhooks that processing happens by hand, which means not at all, and you keep sending to addresses that damage your reputation.
Why doing it by hand does not work
Bounces arrive as mail messages in a mailbox nobody reads, in a format that differs per receiving server. In the first month someone still looks at them; after that, nobody does. Meanwhile your webshop keeps sending order emails to an address that stopped existing a year ago, and your newsletter keeps going to someone who reported you as spam three times. Receiving parties see that and judge all your mail more harshly. How much that weighs is on the deliverability page.
Which events you receive
- Delivered: the receiving server accepted the message. Useful for showing "sent on" in your own system.
- Hard bounce: the address or the domain does not exist. Permanent.
- Soft bounce: a temporary problem: mailbox full, server unreachable, message too large. The platform retries; you get the notification if it ultimately fails.
- Complaint: the recipient clicked "report spam" at a provider that feeds that back.
- Open and click: only for messages with tracking, and with the caveat that opens have become unreliable.
What to do per event
On a hard bounce, put the address on a block list in your own system and show it to whoever manages the record. Do not simply delete it: an employee could enter it again. Mark it as invalid, with date and reason. For a webshop that means asking the customer for a different address at their next order.
On a soft bounce, count. Once is nothing. Three times in a row across several sends, then treat the address as hard after all.
On a complaint, unsubscribe the address from all marketing mail immediately, without asking for confirmation. Whoever clicked "spam" does not want an "are you sure?" email. Transactional mail, such as an order confirmation, may usually continue; that is not marketing.
On delivery you usually do nothing, except store the status so customer service can see that the invoice really did leave and arrive.
How to set it up technically
- Create an endpoint in your application that receives a web call with JSON and quickly answers with a success code. Do the processing afterwards, not during the call; the platform does not wait forever.
- Verify the signature. A good platform signs every webhook. Check it before you process anything, otherwise anyone who knows your endpoint can block your entire list.
- Make processing repeatable. Webhooks can arrive twice when the platform retries. Processing the same bounce twice must not have a second effect.
- Link on your own reference. When sending via the email API, attach a customer number or order number; the webhook returns it, so you do not have to search by email address.
- Log everything. Keep the raw event for a while. In a discussion with a customer, "delivered on Tuesday at 14:02 to their provider's server" is a strong argument.
An example from practice
A service provider sends monthly invoices from its own portal. Previously, accounting phoned customers who had not paid after three weeks, only to hear the invoice never arrived. Now a hard bounce comes in within minutes via the webhook, the portal marks the address as invalid and the file manager sees an alert to ask for a new address. The customer receives the invoice the same day at a correct address, and the wrong address is never used again.
And if you have no software of your own?
Then the platform handles bounces itself: addresses that hard-bounce are automatically suppressed on subsequent sends, and the dashboard shows per message what happened. Webhooks are the next step, for anyone who wants the information in their own CRM or webshop as well.
Frequently asked questions
Do I need to use the API for webhooks?
No. Messages that left via SMTP also produce events. The API only makes it easier to tie them to your own references.
What if my endpoint is offline for a while?
A good platform retries at increasing intervals. Which is why your processing must be repeatable.
Do I receive every complaint?
Only from providers that feed complaints back to senders. The big ones do; some smaller ones do not. That is why your bounce rate remains a signal to watch too.