Czym jest webhook?

Gdy Bird wywołuje Twój endpoint, odbiorca musi utrwalić zdarzenie, zanim zacznie je przetwarzać. Webhook to żądanie HTTP, które jeden system wysyła do Twojej aplikacji, gdy coś się wydarzy. Nadawca podpisuje POST wysyłane na zarejestrowany przez Ciebie URL. Twój odbiorca decyduje, kiedy zdarzenie zostanie trwale zaakceptowane.

Czym webhook różni się od odpytywania API?

Odpytywanie oznacza, że Twoja aplikacja cyklicznie wywołuje API i sprawdza zmiany. Webhook odwraca ten kierunek: dostawca wywołuje Twój endpoint, gdy nastąpi zdarzenie, dzięki czemu unikasz pustych żądań i reagujesz szybciej.

Webhooki wymagają publicznego endpointu HTTPS, który może odbierać żądania w trakcie dostarczania zdarzeń. Odpytywanie działa z dowolnego miejsca i pozwala Twojej aplikacji wybrać moment pobrania stanu. Używaj webhooków do powiadomień wymagających szybkiej reakcji. Używaj API, aby pobrać szczegóły zasobu, gdy zdarzenie zawiera tylko identyfikatory.

Jak wygląda żądanie webhooka?

Żądanie webhooka to HTTP POST z nagłówkami i kopertą zdarzenia JSON. Zdarzenie dostarczenia e-maila w Bird zawiera type, timestamp zdarzenia oraz pola specyficzne dla typu data:

{
  "type": "email.delivered",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "email_id": "em_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient_id": "er_01krdgeqcxet5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient": "user@example.com",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null
  }
}

Identyfikator wiadomości to data.email_id. Tożsamość dostarczenia to nagłówek webhook-id, który pozostaje taki sam, gdy Bird ponawia próbę lub odtwarza to zdarzenie. Pole timestamp w treści rejestruje moment wystąpienia zdarzenia. Nagłówek webhook-timestamp rejestruje tę próbę dostarczenia, więc oba znaczniki czasu odpowiadają na różne pytania. Zobacz pola zdarzeń e-mail, aby poznać ładunki specyficzne dla zdarzeń.

Jak zweryfikować podpis webhooka?

Zachowaj surowe bajty żądania i zweryfikuj podpis przed parsowaniem lub zapisaniem zdarzenia. SDK w Bird sprawdza nagłówki webhook-id, webhook-timestamp i webhook-signature. Stosuje tolerancję znacznika czasu automatycznie. Użyj przewodnika po podpisach zamiast pisać własną weryfikację.

Jeśli chcesz zrozumieć dane wejściowe podpisu, Bird używa {webhook-id}.{webhook-timestamp}.{raw request body}. Sekret endpointu zaczyna się od whsec_; usuń ten prefiks i zdekoduj resztę z base64 przed obliczeniem HMAC-SHA256. Podczas rotacji sekretu nagłówek podpisu może zawierać kilka oddzielonych spacjami wartości v1,, więc akceptuj pasującą wartość spośród aktywnych sekretów.

Odrzucaj nieprawidłowe, nieuwierzytelnione lub przeterminowane żądania przed zapisem. Parsowanie JSON w pierwszej kolejności może zmienić białe znaki lub kolejność kluczy i sprawia, że bajty przestają pasować do podpisanej wiadomości.

Jak przechowywać i potwierdzać webhooka?

Utrwal zweryfikowane zdarzenie i powiązaną trwałą pracę przed zwróceniem sukcesu. Wstaw zdarzenie z kluczem webhook-id. Wstaw element pracy dla nowego zdarzenia. Zatwierdź oba w jednej transakcji lub równoważnym projekcie trwałej skrzynki odbiorczej i nadawczej.

read raw bytes and headers
verify the signature and timestamp with the Bird SDK
begin a durable transaction
  insert the inbox event keyed by webhook-id, unless it already exists
  insert a durable work item for a new event
commit the transaction
return 204
worker processes the persisted event idempotently

Duplikat, który jest już trwale zapisany, może otrzymać 204 bez tworzenia dodatkowej pracy. Zwróć kod inny niż 2xx, gdy trwały zapis się nie powiedzie, aby Bird ponowił dostarczenie. Gdy zwrócisz sukces, ponawiaj lokalny worker z trwałego rekordu zamiast oczekiwać, że Bird wyśle zdarzenie ponownie.

Ta kolejność to wzorzec projektowy aplikacji dla semantyki dostarczania co-najmniej-raz w Bird. To nie jest kolejka, którą Bird prowadzi za Ciebie. Przewodnik po duplikatach i idempotentności szczegółowo opisuje decyzję o deduplikacji.

Jak działają ponowienia i odtwarzanie webhooków?

Bird daje zwykłemu dostarczeniu 15 sekund na otrzymanie odpowiedzi. Każdy status 2xx oznacza sukces. Status inny niż 2xx, przekierowanie lub timeout oznacza niepowodzenie i uruchamia harmonogram ponowień.

Krzywa obejmuje 8 prób, wliczając pierwsze żądanie. Każde opóźnienie podlega odchyleniu ±20% (jitter). 429 lub timeout połączenia podnosi bazowe opóźnienie do 60 sekund. Dodatnia wartość Retry-After jest ograniczana między bazę a dwukrotność bazy przed jitterem, więc tabela opisuje opóźnienia bazowe, a nie dokładne czasy dostarczenia. Zobacz jak ponawiane są nieudane webhooki, aby poznać ścieżkę obsługi błędów.

Dostarczenia nie zachowują kolejności, więc nie aktualizuj bieżącego stanu aplikacji wyłącznie na podstawie kolejności odbioru. Używaj timestamp zdarzenia i stanu zasobu, gdy zdarzenia mogą dotrzeć w zmienionej kolejności.

Gdy dostarczenie zostanie pominięte, sprawdź próby dostarczenia webhooka. Napraw odbiorcę. Utwórz odtworzenie webhooka. Bird pomija dostarczenia, które endpoint już odebrał z sukcesem. Odtworzenie używa oryginalnego webhook-id, więc ten sam klucz deduplikacji je chroni.

Co warto podłączyć po poznaniu podstaw webhooków?

Utwórz endpoint. Zweryfikuj i trwale zaakceptuj podpisane dostarczenia. Sprawdź próby dostarczenia. Odtwórz pominięte zdarzenia. Następnie użyj rotacji sekretów, aby wdrożyć nowy sekret podpisu bez utraty dostarczeń.