Webhooks

Webhooks möjliggör för API konsumenter att bli notifierade när en specifik händelse inträffar i ett API gränssnitt. För att tillgängliggöra detta så ska API konsumenten sätta upp en URL endpoint som kan acceptera och bearbeta en HTTP POST request. Denna endpoint ska också registreras hos API producenten tillsammans med en specifikation på vilka händelser som är intressanta att lyssna på.

Webhooks används i flera olika sammanhang som t.ex. händelser gällande uppdateringar av data hos producenten, eller att meddela att kod är incheckad till ett repository - som i sin tur kanske triggar ett bygge enligt Continuous Integration.

I en API Webhook implementation skickas vanligen payload som ett JSON dokument som förser mottagaren med begränsad information om den inträffade händelsen, t.ex. så kan innehållet bara vara en referens till resursen som har uppdaterats. Det innebär att konsumenten måste göra en request mot ett API för att få denna information i sin helhet.

Om man implementerar en API Webhook som skickar med detaljerna direkt i dess payload, så underlättar man för konsumenten och minskar nättrafiken, men kan bygga komplexitet i design av API:et. Känsligheten i det data som skickas i payload bör beaktas här.

Om Webhooks väljs att implementeras så bör följande designriktlinjer övervägas:

  • Om känslig information skickas i Webhook, SKALL (WEB.01) kryptering/signering övervägas i POST request för att erhålla integritet  och verifikation. TLS certifikat är också ett alternativ. 
  • Ett unikt händelseid/transaktionsid BÖR (WEB.02) inkluderas i POST request, för att underlätta felsökning och loggning.
  • Konsumentens endpoint SKALL (WEB.03) alltid returnera ett svar på inkommen POST, så producenten vet att svaret är levererat.
  • API SKALL (WEB.04) stödja en återsändningsfunktion i de fall  konsumentens URL inte är tillgänglig, eller möjliggöra att konsument gör  en request som använder tidpunkt eller räknare. På detta sätt kan konsumenten antingen få begärd information från producent, eller begära  den själv med senast sparat tidpunkt eller räknare.
  • En tydlig onboarding/offboarding process SKALL (WEB.05) finnas, som beskriver den process som konsumenten genomgår för att börja använda webhooks mot producenten samt hur avslut av samma sker.
  • Eftersom användandet av Webhooks kräver ytterligare infrastruktur hos API konsumenterna, BÖR (WEB.06) detta tas hänsyn till när lösningen designas.