how-to · antwoord met bronnen

Hoe werken webhooks van Resend?

Webhooks van Resend werken door een HTTPS POST met een JSON-eventpayload naar je geregistreerde endpoint te sturen wanneer er een event rond een e-mail, contact, domein of suppressie plaatsvindt. Je endpoint moet de handtekening verifiëren tegen de ruwe request-body, het event idempotent verwerken en snel een succesvolle respons teruggeven.

De webhookworkflow van Resend

De workflow begint wanneer je een openbaar HTTPS-endpoint aanmaakt en het in Resend registreert met de eventtypes die je applicatie nodig heeft. Zodra er een overeenkomend event plaatsvindt, stuurt Resend een POST-request met een JSON-payload. De payload bevat een type zoals email.sent, email.delivered, email.bounced of email.complained, een aanmaaktijd en eventspecifieke data. Routeer de verwerking op basis van het veld type, in plaats van aan te nemen dat elke payload dezelfde vorm heeft.

Verifieer het request voordat je het verwerkt

Lees het request in als ruwe tekst en verifieer het met het signing secret van de webhook plus de headers svix-id, svix-timestamp en svix-signature. Doe dit voordat je de payload parset of er iets mee doet. Als je JSON parset en daarna opnieuw serialiseert, kunnen de bytes veranderen en faalt een legitieme handtekening. Weiger requests die niet door de verificatie komen, en bewaar het signing secret in een secret manager of een beschermde omgevingsvariabele in plaats van in de broncode.

Verwerk events idempotent

Resend documenteert at-least-once-levering, dus hetzelfde event kan je endpoint meer dan eens bereiken. Sla de svix-id op met een uniciteitsbeperking en sla de bedrijfslogica over als die identifier al is verwerkt. Vertrouw ook niet op de volgorde van binnenkomst, want retries en netwerkvertragingen kunnen events door elkaar gooien. Gebruik de created_at-waarde van het event als de volgorde ertoe doet, en modelleer statuswijzigingen zo dat een ouder event niet per ongeluk een nieuwere status kan overschrijven.

Bevestig snel en verwerk veilig

Geef HTTP 200 terug zodra het event is geverifieerd en duurzaam is vastgelegd, en voer langzamer werk daarna uit via een queue of background worker. Een timeout of een niet-succesvolle respons leidt tot een nieuwe leverpoging, dus lange synchrone handlers veroorzaken onnodige duplicaten. Scheid het binnenhalen van events van neveneffecten zoals het bijwerken van een suppressierecord, het informeren van support of het registreren van een bounce. Elk neveneffect moet ook veilig te herhalen zijn of worden afgeschermd met de opgeslagen event-identifier.

Test retries, replays en herstel na fouten

Test het endpoint vóór productie met representatieve eventtypes, inclusief ongeldige handtekeningen, dubbele identifiers, timestamps in de verkeerde volgorde en tijdelijke databasestoringen. Resend doet retries voor mislukte leveringen volgens een backoff-schema en laat je zowel mislukte als geslaagde webhookberichten opnieuw afspelen (replay). Gebruik replay om te herstellen na een storing of om bijgewerkte handlercode te valideren, maar laat deduplicatie actief, zodat het herstel geen neveneffecten richting klanten herhaalt.

Vragen die teams stellen

Welke respons moet een webhookendpoint voor Resend teruggeven?

Geef HTTP 200 terug nadat het request is geverifieerd en het event duurzaam is geaccepteerd. Langzaam werk moet asynchroon doorlopen, zodat de provider geen retry doet vanwege een timeout.

Waarom moet de ruwe request-body behouden blijven?

De handtekening dekt de oorspronkelijke bytes van het request. JSON parsen en opnieuw serialiseren kan die bytes veranderen, waardoor de verificatie faalt, ook als het request legitiem is.

Kan een webhookevent van Resend meer dan eens worden geleverd?

Ja. Resend documenteert at-least-once-levering, dus handlers moeten events dedupliceren, meestal door de unieke svix-id op te slaan voordat er neveneffecten in de bedrijfslogica worden uitgevoerd.

Worden webhookevents van Resend op volgorde geleverd?

Nee. Netwerkvertragingen en retries kunnen de volgorde van binnenkomst veranderen. Gebruik timestamps van events en regels voor statusovergangen als je applicatie een betrouwbare volgorde moet reconstrueren.

Hoe herstel je mislukte webhookleveringen van Resend?

Resend doet automatisch retries voor mislukte leveringen en ondersteunt ook handmatige replay. Repareer eerst het endpoint en speel daarna de benodigde events opnieuw af, met de idempotentiecontroles ingeschakeld.