Configuring a webhook

A webhook is an address on your own server to which 2Mail sends a message as soon as something happens to an email: delivered, bounced, opened. That way your web shop or CRM knows within seconds what became of a message, without you having to look at the dashboard.

What you need

• an address on your server that is reachable over https and can receive requests; a webhook without encryption is not accepted
• a piece of code behind that address that processes the data
• administrator rights in your 2mail account

Step 1: create the webhook

1. Open the webhooks section in the dashboard and create a new one.
2. Enter the address of your endpoint.
3. Choose the events you want to receive: delivery, bounce, open, or a combination. Start with bounces — that is the event you need to act on soonest.
4. Save. The dashboard shows a secret key with which every call is signed. Keep it in the configuration of your application.

Step 2: verify the signature

Anyone can send a request to your address. Every call from 2Mail therefore carries a signature in the header, computed with the secret key over the content. Recompute that signature on your side and reject requests where it does not match. Do not skip this step: without the check, an outsider can make your system believe a message bounced.

Step 3: answer quickly

Respond immediately with a status code in the 200 range and process the data afterwards, for instance through a queue. If your processing takes too long or you answer with an error, 2Mail treats the call as failed and retries later. Make sure your code can receive the same message twice without duplicate actions: use the message identifier to recognise repeats.

Step 4: test

Send a test message to an address you control and check that the delivery arrives at your endpoint. For a bounce, test with an address that certainly does not exist on a domain that does. The dashboard shows the latest calls per webhook, with your server's reply — there you see straight away whether your endpoint returned anything other than a 200.

What to do with it

• On a hard bounce, flag the address in your CRM so a salesperson does not keep using it.
• On a delivery, show in the order history that the confirmation arrived — that saves phone calls.
• On an open, schedule a follow-up task, for instance after a quote.

Where it goes wrong

• No calls — the address is only reachable internally, or a firewall blocks requests from outside.
• Signature never matches — you compute it over modified content; use the raw content of the request.
• Duplicate actions — your endpoint answers too slowly and therefore receives repeats.

Webhooks are part of the email API; creating an API key is the first step if your application wants to send as well.

Still stuck?

Give us the address of your endpoint and the time of the test via contact. We show you what your server answered us.