E-post-webhooks forklart

En webhook er måten tilbyderen din forteller applikasjonen din at noe har skjedd på, uten at applikasjonen din må fortsette å spørre. Når en e-post leveres, returneres eller markeres som søppelpost, sender tilbyderen en HTTP-forespørsel til en URL du kontrollerer, med detaljene om den hendelsen. Koden din reagerer på den der og da.

Her er hva en webhook er, hvilke hendelser du kan forvente, hvorfor signerte webhooks betyr noe, og hvordan du konsumerer dem.

Webhooks vs. pollinger

Uten webhooks er den eneste måten å finne ut hva som skjedde med en melding på, å spørre gjentatte ganger: sende en forespørsel med noen sekunders mellomrom som spør "er denne levert ennå?". Det er polling, og det er sløsing. De fleste forespørslene kommer tilbake uten nytt, du hamrer løs på tilbyderens API til ingen nytte, og du får likevel vite om hendelser sent, bare så ofte som du poller.

En webhook snur det. I stedet for at du spør, forteller tilbyderen deg. I det øyeblikket en hendelse skjer, gjør den en enkelt POST-forespørsel til endepunktet ditt med hendelsesdataene. Du gjør ikke noe arbeid før det er noe å reagere på, og du hører om det umiddelbart. For alt hendelsesdrevet, en returmelding som bør pause en purresekvens, et innkommende svar som bør åpne en kundestøttesak, er webhooks det riktige verktøyet og polling det gale.

De vanlige hendelsestypene for e-post

De fleste e-posthendelser faller inn under en håndfull typer webhooken din vil motta:

• levert - den mottakende serveren godtok meldingen. Bekreftelse på at den kom frem.
• returnert - meldingen kunne ikke leveres. Hendelsen sier om returen var hard eller myk, slik at du kan undertrykke en død adresse eller prøve en midlertidig feil på nytt. Se slik håndterer du returmeldinger.
• klaget - mottakeren markerte meldingen som søppelpost. Et sterkt signal om å slutte å sende til den adressen.
• åpnet - mottakeren åpnet meldingen. Nyttig som et engasjementssignal, men best behandlet som et mykt hint fremfor et hardt faktum, siden bildeblokkering og personvernfunksjoner gjør det upålitelig.
• innkommende mottatt - noen sendte en e-post *til* en av adressene dine, og tilbyderen tolker den og poster den til deg som en hendelse. Dette er slik du bygger svarhåndtering, kundestøtteinnbokser og adressebasert automatisering oppå e-post.

Leveringshendelser og innkommende post kommer gjennom den samme mekanismen: en HTTP-forespørsel til endepunktet ditt som beskriver hva som skjedde.

Hvorfor signerte webhooks betyr noe

Webhook-endepunktet ditt er en offentlig URL. Hvem som helst som får vite den, eller rett og slett gjetter den, kan sende den en POST som ser ut som en ekte hendelse. Hvis du stoler på hver forespørsel som kommer, kan en angriper forfalske en "returnert"-hendelse for å få en ekte kunde undertrykket, eller en falsk "innkommende mottatt" for å injisere en melding i kundestøttekøen din. Et uverifisert webhook-endepunkt er en åpen dør.

Signering lukker den. Tilbyderen beregner en HMAC-signatur over forespørselskroppen ved hjelp av en hemmelighet bare dere to kjenner, og sender den signaturen i en header. Endepunktet ditt beregner signaturen på nytt med den samme hemmeligheten og sjekker at den stemmer. Gjør den det, kom hendelsen virkelig fra tilbyderen din og ble ikke endret underveis. Gjør den det ikke, avviser du forespørselen. Dette er forskjellen mellom å vite at en hendelse er ekte og bare håpe at den er det, og det er derfor du bare bør konsumere webhooks som er signert.

Hvordan du konsumerer dem

Å konsumere webhooks er bevisst enkelt. Du setter opp et lite HTTP-endepunkt og forteller tilbyderen din URL-en. Fra da av:

1. Tilbyderen sender en POST til endepunktet ditt for hver hendelse.
2. Endepunktet ditt verifiserer HMAC-signaturen før det stoler på noe i kroppen.
3. Det leser hendelsen og gjør arbeidet sitt: oppdaterer et register, undertrykker en adresse, åpner en sak.
4. Det returnerer en 2xx-status for å fortelle tilbyderen at hendelsen ble mottatt.

To praktiske regler holder dette robust. Returner `2xx` raskt. Tilbyderen behandler statuskoden din som en kvittering, så kvitter først og gjør tungt arbeid etterpå, helst på en bakgrunnskø, i stedet for å la tilbyderen vente. Forvent gjentatte forsøk. Hvis endepunktet ditt er nede eller returnerer en feil, prøver en god tilbyder hendelsen på nytt senere med gradvis økende ventetid, slik at et kort avbrudd på din side ikke mister hendelser. Baksiden er at du bør gjøre håndtereren din idempotent, for et gjentatt forsøk betyr at du kan se den samme hendelsen mer enn én gang og ikke bør handle på den to ganger.

Slik håndterer Mailhuset det

Mailhuset leverer hver hendelse som en signert webhook. Hver forespørsel bærer en HMAC-signatur beregnet med hemmeligheten din, slik at endepunktet ditt kan verifisere at hendelsen virkelig er fra oss før det handler på den. Leveringshendelser, returer og klager for utgående post, og innkommende meldinger sendt til adressene dine, kommer alle på samme måte: en POST til endepunktet ditt som du verifiserer, håndterer og kvitterer med en 2xx. Mislykkede leveringer prøves på nytt, slik at et øyeblikks avbrudd på din side ikke koster deg en hendelse. Det er alt ett produkt, transaksjonell e-post, innkommende post og masseutsendelser, som sender fra EU som standard.

Se webhooks og innkommende for hvordan du setter opp endepunktet ditt og begynner å motta hendelser.