Webhook vs API: push kontra pull, podpisy, ponowienia | We.Inc
Webhook vs API wyjaśnione z tabelą porównawczą, zaletami i wadami pollingu i push, sprawdzaniem podpisu HMAC w przeglądarce, obsługą ponowień i idempotentnym kodem odbiorcy.
Przy wywołaniu API Twój kod prosi inną usługę o dane wtedy, kiedy chce: to pull. Przy webhooku usługa wysyła HTTP POST na Twój URL w chwili, gdy coś się wydarzy: to push. Większość integracji używa obu: webhooka, aby szybko dowiedzieć się o zmianie, i wywołania API, aby pobrać pełny, aktualny rekord.
Żądanie API vs webhook
Żądanie API (pull)
Webhook (push)
Kto zaczyna
Twój kod
Druga usługa
Moment
Gdy zapytasz albo według timera pollingu
Zaraz po zdarzeniu
Potrzebujesz
Klucza API i klienta
Publicznego endpointu HTTPS
Potwierdzenie nadawcy
Dostawca sprawdza Twój klucz
Ty sprawdzasz podpis dostawcy
Gdy coś zawiedzie
Widzisz błąd i ponawiasz
Dostawca ponawia; musisz obsłużyć duplikaty
Najlepsze do
Odczytu lub zmiany danych na żądanie
Reagowania na zdarzenia, których nie wywołałeś
Odpytywanie API co minutę, czy płatność przeszła, marnuje żądania i nadal przychodzi z opóźnieniem. Webhook odwraca kierunek, ale przenosi też odpowiedzialność na Ciebie: Twój endpoint musi być publiczny, potwierdzać autentyczność każdej wiadomości, odpowiadać szybko i radzić sobie z tym samym zdarzeniem przychodzącym dwa razy. Ta strona omawia każde z tych zadań z kodem do skopiowania.
Zarejestruj u dostawcy URL na swoim serwerze i wybierz zdarzenia, które Cię interesują.
Dostawca podpisuje treść każdego zdarzenia wspólnym sekretem i wysyła ją POST-em na ten URL.
Twój endpoint ponownie oblicza podpis na surowej treści, odrzuca niezgodności i szybko odpowiada kodem 2xx.
Zadanie w tle wykonuje właściwą pracę, pomijając każde id zdarzenia, które już przetworzyło.
Weryfikuj na surowych bajtach treści. Parsowanie i ponowna serializacja JSON zmienia odstępy i psuje podpis.
Porównuj podpisy funkcją o stałym czasie, taką jak crypto.timingSafeEqual, nigdy przez ===.
Zapisuj id przetworzonych zdarzeń z ograniczeniem unique, aby ponowienie lub duplikat stały się nieszkodliwą operacją bez efektu.
Nie zakładaj, że zdarzenia przychodzą po kolei. Gdy kolejność ma znaczenie, pobierz aktualny obiekt z API.
Utrzymuj wolne zadanie uzgadniające, które raz dziennie odpytuje API, aby wyłapać każde zdarzenie, które nigdy nie dotarło.
Najczęściej zadawane pytania
Czy webhook to rodzaj API?
W luźnym sensie tak. To żądanie HTTP z treścią JSON, tylko wysłane w przeciwnym kierunku. Czasem nazywa się go odwróconym API. Istotna różnica polega na tym, kto zaczyna rozmowę i kto musi być online, aby ją odebrać.
Odpytywać czy używać webhooków?
Używaj webhooków, gdy dostawca oferuje je dla potrzebnych Ci zdarzeń i możesz hostować publiczny endpoint HTTPS. Odpytuj, gdy nie ma webhooka, gdy jesteś za firewallem albo przy niewielkiej liczbie sprawdzeń, gdzie minuta opóźnienia nie przeszkadza.
Skąd mam wiedzieć, że webhook naprawdę przyszedł od dostawcy?
Większość dostawców wysyła w nagłówku HMAC SHA-256 treści, obliczony sekretem znanym tylko Tobie i im. GitHub na przykład używa X-Hub-Signature-256 z prefiksem sha256=; Stripe używa Stripe-Signature ze znacznikiem czasu. Oblicz go ponownie i porównaj, zanim czemukolwiek zaufasz.
Co się stanie, jeśli mój endpoint nie działa?
Większość dostawców ponawia nieudane dostarczenia z rosnącymi przerwami między próbami, przez okres zależny od dostawcy. Stripe na przykład ponawia zdarzenia live przez maksymalnie trzy dni. Potem zdarzenie jest dostępne tylko przez jego API lub panel.
Dlaczego obsługa webhooka powinna odpowiedzieć przed wykonaniem pracy?
Dostawcy czekają na odpowiedź tylko krótko. Jeśli Twój kod najpierw wysyła e-maile lub wywołuje inne usługi, dostarczenie może przekroczyć limit czasu i zostać ponowione, mimo że już na nie zareagowałeś. Dodaj zadanie do kolejki, zwróć 200 i przetwarzaj później.
Pull: wywoływanie API
Żądanie API to pytanie, które zadaje Twój kod: daj mi zamówienie 42, wypisz dzisiejsze rejestracje, utwórz tego klienta. Ty wybierasz, kiedy pytać, i od razu dostajesz odpowiedź, w tym jasny błąd, jeśli coś poszło nie tak.
Kosztem jest to, że o zmianach dowiadujesz się tylko wtedy, gdy zapytasz. Aby zauważyć nowe zdarzenia, musisz odpytywać według timera, a większość odpytań wraca pusta.
Push: odbieranie webhooka
Webhook to dostawca dzwoniący do Ciebie. Gdy zdarzenie zachodzi, wysyła POST-em jego opis w JSON na zarejestrowany przez Ciebie URL, zwykle w ciągu kilku sekund.
Ponieważ każdy w internecie może wysłać POST na ten URL, treść jest niezaufana, dopóki jej podpis się nie zgodzi. Ponieważ sieci zawodzą, to samo zdarzenie może przyjść więcej niż raz lub w złej kolejności. Dobry odbiorca jest przygotowany na oba przypadki od pierwszego dnia.
Używanie obu razem
Popularny, solidny wzorzec traktuje webhook jak dzwonek do drzwi. Mówi Ci, który obiekt się zmienił; potem wywołujesz API, aby odczytać aktualny stan tego obiektu i na niego zareagować. To omija problemy z kolejnością i nieaktualnymi danymi, a codzienne odpytanie wyłapuje wszystko, co dzwonek przegapił.
Odbiorca webhooka, który sprawdza podpis
Node i Express: HMAC SHA-256 na surowej treści
express.raw zachowuje treść jako bajty, więc podpis się zgadza. Ten format nagłówka stosuje konwencję sha256= z GitHub; dla innych dostawców dostosuj nazwę nagłówka.
Obsługa ponowień i duplikatów
Unikalny indeks na id zdarzenia sprawia, że przy drugim dostarczeniu insert się nie udaje, więc praca wykonuje się raz, niezależnie od tego, ile razy zdarzenie przyjdzie.
Zapisz każde id zdarzenia raz (PostgreSQL)
ON CONFLICT DO NOTHING nie zwraca wiersza dla duplikatu, co Twój kod traktuje jako już obsłużone.
Alternatywa: polling
Polling łatwiej hostować, ale jest wolniejszy i generuje więcej ruchu. Trzymaj kursor, aby każde odpytanie prosiło tylko o nowe dane.
Sprawdzanie podpisu HMAC SHA-256
Wklej treść i sekret, aby obliczyć podpis, który wysłałby dostawca, a potem wklej otrzymany nagłówek, aby porównać. Wszystko działa w Twojej przeglądarce przez Web Crypto API; nic nie jest nigdzie wysyłane.
Surowa treść żądania
Sekret webhooka
Podpis, który powinna mieć ta treść
Otrzymany nagłówek podpisu (opcjonalnie)
Zgodność: ta treść i sekret dają ten podpis.
Brak zgodności: albo treść się zmieniła, albo sekret jest błędny, albo nagłówek używa innego formatu.