Webhook

Varför de finns

Alternativet är polling – att anropa ett API varje minut och fråga om något förändrats. Det är slöseri när ingenting hänt och långsamt när något har hänt. En webhook gör händelsen pushbaserad: Stripe anropar din endpoint i samma stund som en betalning går igenom, GitHub anropar den när en gren pushas, en formulärtjänst anropar den när ett svar kommer in.

Kravet som följer är lätt att missa: du behöver en publikt nåbar adress som tar emot POST-anrop. En app som bara lever i webbläsaren kan inte ta emot en webhook, eftersom det inte finns något för avsändaren att anropa. Du behöver en server, en serverlös funktion eller en endpoint hos en plattform. Under utveckling får en tunnel som ngrok eller Stripe CLI träda in i stället.

Fyra regler för att hantera dem rätt

1. Verifiera signaturen. Endpointen är publik, så vem som helst som hittar adressen kan posta till den. Leverantörer signerar varje anrop med en delad hemlighet, och verifierar du den inte kan ett förfalskat anrop markera en order som betald. Det är det enskilt vanligaste säkerhetsmisstaget med webhooks.
2. Svara snabbt, arbeta efteråt. Returnera 200 inom ett par sekunder och gör det verkliga arbetet i bakgrunden. Långsamma hanterare tolkas som misslyckanden och görs om.
3. Räkna med dubbletter. Omförsök och nätverksglapp gör att samma händelse kan komma två gånger. Spara händelsens id och ignorera sådant du redan behandlat – alternativet är att debitera eller mejla en kund dubbelt.
4. Räkna med fel ordning. payment.succeeded kan komma före order.created. Hanterare bör titta på nuvarande tillstånd i stället för att anta en sekvens.

De flesta leverantörer gör om misslyckade leveranser med gradvis längre mellanrum i timmar eller dygn och stänger sedan av endpointen. En vy över de senaste leveranserna är oftast snabbaste vägen att felsöka varför ingenting kom fram.

Inte samma sak som ett API du anropar

Missuppfattningen är att se webhook och REST-API som konkurrerande val. De kompletterar varandra: webhooken berättar att något hänt, och sedan anropar du normalt leverantörens API för att hämta det aktuella och auktoritativa tillståndet i stället för att lita på nyttolasten ensam.