Nøglepunkter
- Bekræft hurtigt med et 2xx-svar, og lav arbejdet bagefter i en kø.
- Regn med dubletter og hændelser i forkert rækkefølge; gør behandlingen idempotent.
- Verificér signaturen over de nøjagtige bytes, du modtog, og afvis gamle tidsstempler.
- Afstem: Slå beskeder op, der aldrig når en endelig status.
Derfor slår webhooks polling
At spørge API’et om status på hver besked spilder kald og tilføjer forsinkelse. Med en webhook kalder udbyderen dig, når en status ændres, så dit system kan reagere på sekunder: vise en kode som leveret, udløse en fallback eller opdatere en ordre.
Det kan gå galt
- Dubletter: Levering sker som regel mindst én gang, så den samme hændelse kan komme flere gange
- Rækkefølge: En senere status kan komme før en tidligere
- Forsinkelse: En status kan komme minutter eller timer efter afsendelsen eller slet ikke
- Nedetid: Hvis dit endepunkt er nede, prøves hændelser igen i en begrænset periode og droppes derefter
Designregler for endepunktet
- Returnér en 2xx-status, så snart anmodningen er gemt; lav behandlingen i en kø
- Nøgl hver opdatering på besked-ID og status, så en gentagelse ikke ændrer noget
- Flyt aldrig en besked baglæns: Når den er leveret eller fejlet, så ignorér en tidligere status
- Gem den rå payload en tid til fejlsøgning
- Gør endepunktet billigt og hurtigt; et langsomt endepunkt ligner et, der fejler
Verificér det, du modtager
Alle kan kalde en offentlig adresse, så tjek, at anmodningen kom fra din udbyder. En almindelig metode er en signatur: Afsenderen beregner en nøglet hash over et tidsstempel og den rå body og sender den i en header. Du beregner den samme værdi med din hemmelighed og sammenligner.
Beregn den over de nøjagtige bytes, du modtog, og ikke en omserialiseret kopi, sammenlign i konstant tid, og afvis tidsstempler, der er for gamle, så en opsnappet anmodning ikke kan afspilles igen.
Afstem hullerne
Kør et job, der leder efter beskeder, som ikke har fået en endelig status i længere tid end din normale forsinkelse, og spørg API’et om deres status. Det fanger hændelser, der gik tabt, og viser dig, om et land eller en rute er stille.
Hvordan ZafeConnect passer ind
ZafeConnect sender en POST til din webhook-adresse, når en beskedstatus ændres, med headerne X-ZafeConnect-Event, X-ZafeConnect-Timestamp og X-ZafeConnect-Signature. Signaturen er en hex-HMAC-SHA256 over tidsstemplet, et punktum og den rå body. Returnér et vilkårligt 2xx for at bekræfte; ZafeConnect prøver op til 5 gange igen, hvis dit endepunkt ikke bekræfter. Udviklerdokumentationen har detaljerne.