Transactionele webhooks

Met webhooks kan je applicatie realtime meldingen ontvangen wanneer er iets gebeurt met een transactionele e-mail nadat hij is verstuurd. In plaats van de API te pollen om de bezorgingsstatus te controleren, stuurt Flexmail een HTTP POST-verzoek naar je endpoint op het moment dat een event plaatsvindt.

Dit is bijzonder waardevol voor transactionele e-mail: je kunt direct actie ondernemen wanneer een wachtwoordreset bounced, wanneer een orderbevestiging is bezorgd, of wanneer een ontvanger een bericht als spam markeert.

Webhook-events

Flexmail stuurt een webhookmelding voor elk van de volgende events:

  • Verzonden — het bericht is geaccepteerd en overgedragen aan de ontvangende mailserver.
  • Geweigerd — het bericht werd geweigerd door Flexmail en werd niet verzonden.
  • Bezorgd — de ontvangende mailserver heeft bevestigd dat het bericht werd geaccepteerd voor verdere verwerking.
  • Gebounced — bezorging is mislukt. Hard bounces duiden op een permanent probleem (adres bestaat niet); soft bounces duiden op een tijdelijk probleem (mailbox vol, server niet beschikbaar).
  • Geopend — de ontvanger heeft het bericht geopend.
  • Geklikt — de ontvanger heeft op een gevolgd link in het bericht geklikt.

Opgelet

Open- en kliktracking vereist dat trackingpixels en link-wrapping zijn ingeschakeld. Bezorgingsevents zijn afhankelijk van de ontvangende mailserver die bezorging bevestigt — niet alle servers doen dit.

Een webhook-endpoint instellen

Je webhook-endpoint is een URL op je server die HTTP POST-verzoeken accepteert en een 200-antwoord teruggeeft als bevestiging van ontvangst.


Vereisten voor je endpoint

  • Accepteert HTTP POST-verzoeken.
  • Is publiekelijk toegankelijk via HTTPS.
  • Geeft binnen een redelijke timeout een 2xx HTTP-statuscode terug ter bevestiging van ontvangst.
  • Verwerkt de payload asynchroon als je verwerkingslogica traag is — antwoord direct en verwerk op de achtergrond om timeouts te voorkomen.

Je endpoint registreren in Flexmail

Webhook-endpoint-configuratie verloopt via de API. Het volledige registratieproces en de beschikbare opties zijn gedocumenteerd in de API-documentatie op email-api.flexmail.eu/documentation, onder de sectie Webhooks.

Webhook-payload

Elke webhookmelding is een HTTP POST-verzoek met een JSON-body. De payload bevat het eventtype, een tijdstempel, het bericht-ID en het e-mailadres van de ontvanger. Afhankelijk van het event worden extra velden toegevoegd — een bounce-event bevat bijvoorbeeld het bouncetype en de reden, en een klik-event bevat de URL die werd aangeklikt.

Een typische payload ziet er als volgt uit:


{
	"event": "delivered",
	"timestamp": "2024-11-15T09:32:00Z",
	"messageId": "abc123",
	"recipient": "customer@example.com"
}

De volledige payloadspecificatie voor elk eventtype is te vinden in de API-documentatie: email-api.flexmail.eu/documentation/webhooks

Wat te doen met webhook-events


Bounces

Wanneer je een hard-bounce-event ontvangt, markeer dat e-mailadres dan in je systeem. Stop met verzenden naar dit adres en onderzoek of het adres correct is ingevoerd. Doorgaan met verzenden naar hard-gebounced adressen schaadt je afzendersreputatie.


Spamklachten

Wanneer een ontvanger een transactionele e-mail als spam markeert, onderdruk dat adres dan onmiddellijk. Ook als de e-mail oprecht transactioneel was (een orderbevestiging, bijvoorbeeld), heeft de ontvanger aangegeven geen e-mail van je te willen ontvangen. Doorgaan met verzenden schaadt je reputatie en kan juridische gevolgen hebben.


Bezorgingsbevestigingen

Voor tijdgevoelige berichten zoals wachtwoordresets of tweefactorauthenticatiecodes kun je het bezorgingsevent gebruiken om te bevestigen dat de e-mail de inbox heeft bereikt. Als er geen bezorgingsbevestiging aankomt binnen een redelijke periode, kun je in je gebruikersinterface een melding tonen die de gebruiker vraagt zijn spammap te controleren of het opnieuw te proberen.


Support tip

Bevestig webhook-verzoeken direct met een 200 -antwoord en verwerk de payload daarna in een achtergrondtaak of wachtrij. Als je handler te lang nodig heeft om te antwoorden, kan Flexmail een timeout krijgen en het verzoek opnieuw proberen, wat tot dubbele verwerking kan leiden.

Nieuwe pogingen

Als je endpoint geen succesvolle respons teruggeeft, probeert Flexmail de webhookmelding opnieuw. Maak je event-verwerking idempotent — het tweemaal verwerken van hetzelfde event moet hetzelfde resultaat opleveren als het eenmalig verwerken. Gebruik het bericht-ID en het eventtype samen om duplicaten te filteren.

Volgende stappen

Heeft dit je vraag beantwoord? Bedankt voor je feedback Er is een probleem opgetreden bij het registreren van je feedback. Probeer het later opnieuw.

Nog niet gevonden waar je naar op zoek was Contacteer ons Contacteer ons