Publiczny adres URL odbiorczy może przyjmować żądania od każdego. Atakujący może wysłać sfabrykowane zdarzenie na ten adres, więc żądanie wymaga uwierzytelnienia, zanim wywoła jakiekolwiek działanie.
Bird używa schematu Standard Webhooks signing scheme. Uwierzytelnia identyfikator zdarzenia i czas próby dostarczenia razem z ciałem żądania, więc zmiana któregokolwiek z nich unieważnia podpis.
Co podpisuje Bird?
Bird podpisuje identyfikator zdarzenia, znacznik czasu próby dostarczenia i surowe ciało żądania połączone kropkami.
Nie zmieniaj ciała żądania, dopóki nie zweryfikujesz podpisu. Parsowanie i serializacja JSON mogą zmienić bajty podpisane przez Bird.
| Nagłówek | Co zawiera |
|---|---|
webhook-id | Identyfikator zdarzenia, taki sam przy ponowieniach i powtórzeniach. |
webhook-timestamp | Czas próby dostarczenia jako uniksowy znacznik czasu w sekundach. |
webhook-signature | Jeden lub więcej podpisów rozdzielonych spacjami. Każdy zaczyna się od v1,. |
Przekonwertuj znacznik czasu z sekund, zanim porównasz go z zegarem podającym milisekundy.
Usuń prefiks whsec_ z sekretu endpointu i zdekoduj resztę z base64, aby odzyskać bajty klucza.
Połącz identyfikator, znacznik czasu i niezmienione ciało żądania kropkami. Oblicz HMAC-SHA256 na tym ciągu znaków, używając zdekodowanego klucza. Porównaj wynik z każdym dostarczonym podpisem za pomocą porównania w stałym czasie, którego czas wykonania nie ujawnia, które bajty się zgadzają.
Dlaczego mój podpis nigdy nie pasuje?
Błędny sekret lub zmienione ciało żądania mogą powodować niepowodzenie każdego sprawdzenia podpisu.
Frameworki webowe często parsują JSON przed uruchomieniem handlera. Ponowna serializacja tego obiektu może zmienić białe znaki, kolejność kluczy lub formatowanie liczb. Wynikowy JSON może oznaczać to samo, ale generować inny podpis.
Skonfiguruj tę trasę tak, aby zachowywała surowe ciało żądania. Sprawdź, czy sekret należy do tego endpointu, zwłaszcza po wdrożeniu lub rotacji.
Co powinien odrzucać mój handler?
Odrzuć żądanie, gdy żaden podpis nie pasuje lub podpisany znacznik czasu wykracza poza dozwolone okno czasowe.
Sprawdź każdy podpis w webhook-signature. Podczas rotacji sekretu dostarczenie zawiera podpisy z wielu ważnych sekretów. Akceptowanie dowolnego pasującego podpisu pozwala odbiorcom korzystającym z obu sekretów kontynuować działanie.
Zastosuj pięciominutową tolerancję znacznika czasu po obu stronach zegara. Przechwycone żądanie sprzed dziesięciu minut zostanie wówczas odrzucone, nawet jeśli jego podpis jest poprawny. Utrzymuj dokładny zegar serwera, aby nie odrzucać prawdziwych dostarczeń.
Sprawdź webhook-id względem zdarzeń, które już zapisałeś. Rozpoznany duplikat powinien otrzymać odpowiedź sukcesu bez powtarzania przetwarzania, ponieważ ponowienie tego samego dostarczenia nie dodaje nowego zdarzenia.
Co się stanie, jeśli odrzucę dostarczenie?
Bird ponawia dostarczenie, które otrzymało odpowiedź z błędem lub nie otrzymało odpowiedzi przed upływem limitu czasu.
Odpowiedź 400 na przykład rejestruje odrzucenie i pozostawia dostarczenie kwalifikujące się do ponowienia. Wszystkie odpowiedzi inne niż 2xx podlegają polityce ponowień. Kod pomaga zdiagnozować błąd w logach.
Harmonogram obejmuje w przybliżeniu 27,5 godziny przed korektami, co daje czas na naprawę błędnego sekretu. Ponowienia nieudanych webhooków opisuje harmonogram i sposób powtórzenia pominiętych zdarzeń.
Zwróć 2xx dopiero po zweryfikowaniu i bezpiecznym zapisaniu zdarzenia lub rozpoznaniu już zapisanego duplikatu. Bird pomija udane dostarczenia podczas powtórzenia, więc potwierdzenie niezweryfikowanego żądania uniemożliwia odzyskanie za pomocą tego mechanizmu.
Czy muszę samodzielnie implementować weryfikację?
Nie musisz samodzielnie implementować weryfikacji, jeśli używasz webhooks.unwrap w Bird SDK. Przekaż mu surowe ciało żądania i nagłówki.
Helper sprawdza podpis i znacznik czasu, zanim zwróci zdekodowane zdarzenie. Twoja aplikacja nadal deduplikuje po webhook-id, ponieważ to ona jest właścicielem rejestru wykonanych operacji.
Kompatybilna biblioteka weryfikacji Standard Webhooks może wykonać te same sprawdzenia. Przewodnik po webhookach zawiera przykłady i ręczną implementację.
W skrócie
Weryfikuj oryginalne bajty.
Parsowanie i serializacja JSON mogą zmienić bajty podpisane przez Bird. Zachowaj surowe ciało żądania do weryfikacji.
Sprawdzaj czas oprócz podpisu.
Pięciominutowa tolerancja znacznika czasu ogranicza ponowne użycie przechwyconych żądań. Deduplikuj zapisane zdarzenia osobno po webhook-id.
Sprawdź każdy dostarczony podpis.
Rotacja tworzy nakładające się podpisy. Dopasowanie do dowolnego ważnego podpisu pozwala kontynuować wdrożenie.
Potwierdzaj tylko zweryfikowane, zapisane zdarzenia.
Bird ponawia odpowiedzi inne niż 2xx i pomija udane dostarczenia podczas powtórzenia. Zwracaj sukces dla duplikatów, które już zapisałeś, bez powtarzania ich przetwarzania.