Webhook vs API: wanneer ophalen en wanneer laten pushen

Webhook vs API

Webhook vs API: push vs pull, handtekeningen, retries | We.Inc

Webhook vs API uitgelegd met een vergelijkingstabel, de afwegingen tussen polling en push, een HMAC-handtekeningcontrole in de browser, retries en idempotente ontvangercode.

Bij een API-aanroep vraagt uw code een andere dienst om data wanneer het uitkomt: dat is pull. Bij een webhook stuurt de dienst een HTTP POST naar uw URL op het moment dat er iets gebeurt: dat is push. De meeste integraties gebruiken beide, een webhook om snel van een wijziging te horen en een API-aanroep om het volledige, actuele record op te halen.

API-verzoek vs webhook

API-verzoek (pull)
Webhook (push)

Wie begint
Uw code
De andere dienst

Timing
Als u erom vraagt, of op een pollingtimer
Direct na het event

U hebt nodig
Een API-sleutel en een client
Een openbaar HTTPS-endpoint

De afzender bewijzen
De provider controleert uw sleutel
U controleert de handtekening van de provider

Als het misgaat
U ziet de fout en probeert opnieuw
De provider probeert opnieuw; u moet dubbele berichten afhandelen

Het best voor
Data op verzoek lezen of wijzigen
Reageren op events die u niet zelf veroorzaakte

Elke minuut een API pollen om te zien of een betaling is verwerkt, verspilt verzoeken en is toch te laat. Een webhook draait de richting om, maar legt ook verantwoordelijkheid bij u: uw endpoint moet openbaar zijn, van elk bericht bewijzen dat het echt is, snel antwoorden en ermee omgaan dat hetzelfde event twee keer binnenkomt. Deze pagina behandelt elk van die taken met code die u kunt kopiëren.

Registreer bij de provider een URL op uw server en kies de events die u belangrijk vindt.
De provider ondertekent de body van elk event met een gedeeld geheim en POST het naar die URL.
Uw endpoint berekent de handtekening opnieuw over de ruwe body, weigert afwijkingen en antwoordt snel met 2xx.
Een achtergrondtaak doet het echte werk en slaat elk event-id over dat al verwerkt is.

Controleer tegen de ruwe bytes van de body. JSON parsen en opnieuw serialiseren verandert de spaties en breekt de handtekening.
Vergelijk handtekeningen met een constant-time-functie zoals crypto.timingSafeEqual, nooit met ===.
Sla verwerkte event-id's op met een unique constraint, zodat een retry of dubbel bericht onschadelijk niets doet.
Ga er niet van uit dat events op volgorde binnenkomen. Haal het actuele object op via de API als volgorde ertoe doet.
Houd een trage reconciliatietaak die de API één keer per dag pollt, om elk event te vangen dat nooit aankwam.

Veelgestelde vragen

Is een webhook een soort API?

In grote lijnen wel. Het is een HTTP-verzoek met een JSON-body, alleen in de omgekeerde richting verstuurd. Mensen noemen het soms een omgekeerde API. Het verschil dat telt, is wie het gesprek begint en wie online moet zijn om het te ontvangen.

Moet ik pollen of webhooks gebruiken?

Gebruik webhooks als de provider ze aanbiedt voor de events die u nodig hebt en u een openbaar HTTPS-endpoint kunt hosten. Poll als er geen webhook is, als u achter een firewall zit, of voor een klein aantal controles waarbij een minuut vertraging geen probleem is.

Hoe weet ik dat een webhook echt van de provider komt?

De meeste providers sturen een HMAC SHA-256 van de body in een header, berekend met een geheim dat alleen u en zij kennen. GitHub gebruikt bijvoorbeeld X-Hub-Signature-256 met een sha256=-voorvoegsel; Stripe gebruikt Stripe-Signature met een tijdstempel. Bereken hem opnieuw en vergelijk voordat u iets vertrouwt.

Wat gebeurt er als mijn endpoint plat ligt?

De meeste providers proberen mislukte leveringen opnieuw met steeds grotere tussenpozen, gedurende een periode die per provider verschilt. Stripe blijft live events bijvoorbeeld tot drie dagen opnieuw proberen. Daarna is het event alleen nog beschikbaar via hun API of dashboard.

Waarom moet een webhook-handler antwoorden voordat hij het werk doet?

Providers wachten maar kort op een antwoord. Als uw code eerst e-mails verstuurt of andere diensten aanroept, kan de levering een time-out krijgen en opnieuw worden geprobeerd, terwijl u er al op had gereageerd. Zet de taak in een wachtrij, geef 200 terug en verwerk daarna.

Pull: een API aanroepen

Een API-verzoek is een vraag die uw code stelt: geef me bestelling 42, toon de aanmeldingen van vandaag, maak deze klant aan. U kiest wanneer u het vraagt en krijgt meteen antwoord, inclusief een duidelijke fout als er iets misging.
Het nadeel is dat u alleen van wijzigingen hoort als u erom vraagt. Om nieuwe events op te merken moet u op een timer pollen, en de meeste polls komen leeg terug.

Push: een webhook ontvangen

Een webhook is de provider die u belt. Als het event plaatsvindt, POST hij een JSON-beschrijving ervan naar de URL die u registreerde, meestal binnen enkele seconden.
Omdat iedereen op internet naar die URL kan POSTen, is de body onbetrouwbaar tot de handtekening klopt. Omdat netwerken falen, kan hetzelfde event meer dan eens of in de verkeerde volgorde binnenkomen. Een goede ontvanger is vanaf dag één op beide gebouwd.

Beide samen gebruiken

Een gangbaar, robuust patroon behandelt de webhook als deurbel. Hij vertelt u welk object veranderde; daarna roept u de API aan om de actuele toestand van dat object te lezen en daarop te handelen. Zo omzeilt u problemen met volgorde en verouderde payloads, en een dagelijkse poll vangt alles wat de deurbel miste.

Een webhook-ontvanger die de handtekening controleert

Node en Express: HMAC SHA-256 over de ruwe body

express.raw houdt de body als bytes zodat de handtekening klopt. Dit headerformaat volgt de sha256=-conventie van GitHub; pas de headernaam aan voor andere providers.

Retries en dubbele berichten afhandelen

Een unieke index op het event-id laat de insert bij een tweede levering mislukken, zodat het werk één keer draait, hoe vaak het event ook binnenkomt.

Elk event-id één keer vastleggen (PostgreSQL)

ON CONFLICT DO NOTHING geeft geen rij terug bij een duplicaat, wat uw code behandelt als al afgehandeld.

Het alternatief: pollen

Pollen is eenvoudiger te hosten, maar trager en spraakzamer. Houd een cursor bij zodat elke poll alleen vraagt om wat nieuw is.

HMAC SHA-256-handtekeningcontrole

Plak een body en een geheim om de handtekening te berekenen die een provider zou sturen, en plak daarna de ontvangen header om te vergelijken. Alles draait in uw browser met de Web Crypto API; er wordt niets verstuurd.

Ruwe request-body

Webhook-geheim

Handtekening die deze body zou moeten hebben

Ontvangen handtekeningheader (optioneel)

Komt overeen: deze body en dit geheim geven deze handtekening.

Komt niet overeen: de body is veranderd, het geheim klopt niet, of de header gebruikt een ander formaat.