Webhook

Et webhook er en automatisk besked fra ét system til et andet, som bliver sendt, når en bestemt hændelse sker. En betalingsløsning kan eksempelvis sende et webhook til en webshop, når en betaling er gennemført. Webshoppen kan derefter markere ordren som betalt.

Webhooket består typisk af en HTTP-anmodning til en aftalt URL. Beskeden indeholder oplysninger om hændelsen, ofte som JSON. Modtageren har et endpoint — en adresse, der er bygget til at tage imod, kontrollere og behandle beskeden.

Et webhook er ikke det samme som en API, selv om de ofte arbejder sammen. Med en almindelig API spørger system A typisk system B: “Er der sket noget nyt?” Med et webhook siger system B selv til, når hændelsen sker. Det er forskellen på at ringe hvert femte minut og at få en besked.

Webhooks bruges til betalinger, ordrestatus, formularer, lagerændringer, supporttickets, publicering og mange andre automatiseringer. De er særligt nyttige, når data skal flyttes hurtigt mellem systemer uden konstant polling.

De er heller ikke magi. Beskeden kan komme to gange, blive forsinket eller fejle undervejs. En stabil løsning skal derfor kunne genkende dubletter, validere afsenderen og genbehandle fejl. Det er den del, man ikke ser i den flotte pil mellem to logoer.

Definér først hændelsen præcist. “Når en ordre ændres” er bredt. “Når betalingen er bekræftet” eller “når ordren sendes” er handlingsbart. Abonnér kun på de events, som modtageren faktisk bruger. Ellers drukner loggen i støj.

Beskyt endpointet med HTTPS og kontrollér webhookets signatur eller hemmelige nøgle. En offentlig URL kan kaldes af andre end den rigtige leverandør. Afsenderens dokumentation beskriver normalt, hvordan signaturen beregnes og verificeres.

Svar hurtigt med en korrekt HTTP-status og flyt tungt arbejde til en kø. Hvis endpointet bruger 40 sekunder på at generere en PDF og sende tre mails, kan afsenderen tro, at leveringen fejlede og prøve igen. Gem beskeden, bekræft modtagelsen og behandl arbejdet separat.

Gør behandlingen idempotent. Det betyder, at samme besked kan behandles flere gange uden at skabe flere resultater. Et betalingswebhook må ikke oprette tre ordrer, fordi leverandøren sendte eventet igen. Brug event-ID eller en anden unik nøgle i databasen.

Log modtagelse, kontrol, resultat og fejl. Gem nok til at kunne forklare, hvad der skete, men undgå unødvendige personoplysninger. En log skal hjælpe ved fejlfinding, ikke blive et hemmeligt ekstra kunderegister.

Lav en manuel genkørsel eller et værktøj til mislykkede leverancer. Flere leverandører kan selv forsøge igen, men modtagersystemet bør også have en plan. Overvåg, hvis der pludselig ikke kommer webhooks. Stilhed kan være en fejl, ikke et tegn på, at alt er roligt.

En WooCommerce-butik bruger en ekstern betalingsudbyder. Kunden gennemfører betalingen, men lukker browseren, før hun bliver sendt tilbage til webshoppen. Hvis ordren kun opdateres via retursiden, kan betalingen være gennemført, mens ordren står som afventende.

Betalingsudbyderen sender derfor et webhook med eventet “payment.completed”. Webshoppen verificerer signaturen, finder ordren via betalingsreferencen og kontrollerer, om event-ID’et allerede er behandlet. Derefter opdateres status og lager.

Webshoppen svarer hurtigt med status 200. En separat proces sender ordrebekræftelse og starter pakningen. Hvis mailsystemet er nede, ændrer det ikke ved, at betalingen allerede er registreret. Fejlen kan genbehandles uden at kunden trækkes igen.

En dag sender udbyderen samme event to gange på grund af et midlertidigt netværksproblem. Den anden besked bliver genkendt på event-ID’et og markeres som dublet. Ingen ekstra ordre, ingen ekstra mail og ingen lagerforskel.

Løsningen kobler WooCommerce og betalingssystemet, men den kræver stadig backup, overvågning og dokumentation. Et webhook er transporten af en hændelse. Den forretningsmæssige regel — hvornår en vare må sendes — ligger i modtagersystemet.

Den farligste fejl er at stole på indholdet uden at kontrollere afsenderen. En angriber kan forsøge at kalde endpointet med en falsk “betaling gennemført”. Signaturvalidering og serverens øvrige sikkerhed er ikke valgfri pynt.

En anden fejl er at antage rækkefølge. Eventet “ordre opdateret” kan i nogle systemer ankomme før “ordre oprettet”, eller en forsinket besked kan lande efter en nyere. Brug tidsstempel, versionsnummer eller hent den aktuelle tilstand via API’en, når det er nødvendigt.

Pas på skjulte afhængigheder. Hvis en WordPress-plugin modtager webhooks, og pluginet deaktiveres under en opdatering, kan hændelser blive tabt. Planlæg kø, retry og vedligeholdelsesvinduer.

Til sidst er der testmiljøet. Testwebhooks må ikke ramme den levende database, og livewebhooks må ikke ende i stagingmiljøet. Brug separate nøgler, endpoints og tydelig navngivning.

Webhook-payloads er ofte mindre end et fuldt API-svar. De kan indeholde event-ID og nøgleoplysninger, hvorefter modtageren henter den aktuelle ressource via API’en. Det kan være sikrere og mere robust end at stole på en stor gammel payload.

Mange platforme forsøger automatisk levering igen med stigende pauser. Derfor kan en gammel hændelse dukke op senere. Gem behandlingsstatus længe nok til, at dubletter fortsat kan genkendes.

Webhooket kan også bruges i server-side tracking, hvor en ordre eller et lead sendes fra serveren til et analysesystem. Det kræver stadig samtykke, dataminimering og kontrol. En servervej gør ikke behandlingen lovlig af sig selv.

En integration bør dokumentere eventnavne, payload, signatur, svar, retry og ansvar. Et diagram kan give overblik, men det er den konkrete dokumentation, der gør, at nogen kan reparere integrationen to år senere. Læs også om CMS og valg af platform.

Test ugyldig signatur, tom payload, ukendt event, timeout, dublet og midlertidig databasefejl. Endpointet skal afvise det forkerte og kunne modtage det rigtige igen senere uden at skabe dobbelt resultat.

Prøv også at deaktivere den afhængige tjeneste. Hvis mailsystemet er nede, bør betalingsregistreringen stadig kunne gennemføres. Del processen op efter, hvad der er kritisk, og hvad der kan vente.

En webhook er først færdig, når nogen kan se, om den fejler. Log tidspunkt, eventtype, afsender, svarstatus og et sikkert reference-ID. Undgå at skrive adgangskoder, fulde betalingsdata eller andre følsomme oplysninger i loggen. Den skal hjælpe med fejlsøgning uden selv at blive et dataproblem.

Aftal hvem der reagerer på fejl, og hvor hurtigt. En manglende marketinghændelse kan måske vente til næste arbejdsdag. En betalt ordre, der ikke kommer videre til lageret, kræver en anden alarm. Kritikaliteten bør styre overvågningen — ikke hvor spændende integrationen var at bygge.

På en webshop kan et event eksempelvis oprette en forsendelse, opdatere lager eller sende data til økonomi. På en hjemmeside kan en formular sende en sag til et CRM. I begge tilfælde skal den oprindelige handling stadig kunne dokumenteres, hvis modtagersystemet er nede.

Ved ændringer i payloaden bør der bruges versionsstyring eller en aftalt overgang. Hvis afsenderen pludselig omdøber customer_id, kan modtageren stoppe uden et synligt problem på websitet. Test nye versioner i et stagingmiljø, og behold mulighed for at afspille fejlede events.

En webhook erstatter heller ikke almindelig synkronisering i alle tilfælde. Skal to systemer kunne genopbygge en komplet historik, kan der også være brug for periodiske kontroller via en API. Webhooken fortæller, at noget skete; API’et kan hjælpe med at hente den aktuelle sandhed.

Lav desuden en manuel nødprocedure. Hvis webhooken er nede i to timer, skal medarbejderen vide, hvor de manglende hændelser kan findes, og hvordan de sendes igen uden dubletter. Det er især vigtigt omkring betalinger, bookinger og lager. En integration er mere robust, når virksomheden kan arbejde videre, mens fejlen bliver rettet.

Gennemgå til sidst integrationen, når et af systemerne opdateres. Et webhook-endpoint kan virke upåklageligt i flere år og derefter fejle, fordi et felt, certifikat eller sikkerhedskrav ændres. En årlig teknisk gennemgang og en kendt testhændelse er billigere end at opdage problemet gennem en kunde, hvis ordre ikke blev behandlet.