Een webhook configureren

Een webhook is een adres op uw eigen server waar 2Mail een bericht naartoe stuurt zodra er iets gebeurt met een e-mail: afgeleverd, gebounced, geopend. Zo weet uw webshop of CRM binnen enkele seconden wat er met een bericht gebeurd is, zonder dat u het dashboard hoeft te bekijken.

Wat u nodig hebt

• een adres op uw server dat via https bereikbaar is en verzoeken kan ontvangen; een webhook zonder versleuteling wordt niet aanvaard
• een stukje code achter dat adres dat de gegevens verwerkt
• beheerdersrechten in uw 2mail-account

Stap 1: de webhook aanmaken

1. Open in het dashboard het onderdeel met de webhooks en maak een nieuwe aan.
2. Vul het adres van uw eindpunt in.
3. Kies de gebeurtenissen die u wilt ontvangen: aflevering, bounce, opening, of een combinatie. Begin met bounces — dat is de gebeurtenis waar u het snelst iets mee moet doen.
4. Bewaar. Het dashboard toont een geheime sleutel waarmee elke oproep ondertekend wordt. Bewaar die in de configuratie van uw toepassing.

Stap 2: de handtekening controleren

Iedereen kan een verzoek naar uw adres sturen. Elke oproep van 2Mail draagt daarom een handtekening in de kop, berekend met de geheime sleutel over de inhoud. Bereken die handtekening aan uw kant opnieuw en verwerp verzoeken waarvan ze niet klopt. Sla deze stap niet over: zonder controle kan een buitenstaander uw systeem doen geloven dat een bericht gebounced is.

Stap 3: snel antwoorden

Antwoord meteen met een statuscode in de 200-reeks en verwerk de gegevens daarna, bijvoorbeeld via een wachtrij. Duurt uw verwerking te lang of antwoordt u met een fout, dan beschouwt 2Mail de oproep als mislukt en probeert het later opnieuw. Zorg dat uw code hetzelfde bericht twee keer kan ontvangen zonder dubbele acties: gebruik de identificatie van het bericht om herhalingen te herkennen.

Stap 4: testen

Verstuur een testbericht naar een adres dat u beheert en kijk of de aflevering binnenkomt op uw eindpunt. Voor een bounce test u met een adres dat zeker niet bestaat op een domein dat wel bestaat. Het dashboard toont per webhook de laatste oproepen, met het antwoord van uw server — daar ziet u meteen of uw eindpunt iets anders dan een 200 teruggaf.

Wat u ermee doet

• Bij een harde bounce het adres in uw CRM markeren, zodat een verkoper het niet blijft gebruiken.
• Bij een aflevering in de orderhistoriek tonen dat de bevestiging aangekomen is — dat bespaart telefoontjes.
• Bij een opening een opvolgtaak plannen, bijvoorbeeld na een offerte.

Waar het misgaat

• Geen oproepen — het adres is enkel intern bereikbaar, of een firewall blokkeert verzoeken van buitenaf.
• Handtekening klopt nooit — u berekent ze over een aangepaste inhoud; gebruik de ruwe inhoud van het verzoek.
• Dubbele acties — uw eindpunt antwoordt te traag en krijgt daardoor herhalingen.

Webhooks horen bij de e-mail-API; een API-sleutel aanmaken is de eerste stap als uw toepassing ook wil versturen.

Lukt het niet?

Geef ons via contact het adres van uw eindpunt en het tijdstip van de test. Wij tonen u wat uw server ons antwoordde.