Dlaczego zdarzenia webhook są dostarczane więcej niż raz i jak zapewnić idempotentność przetwarzania?
Poziom ważności: WysokiWstrzymanie wysyłki: Wstrzymaj warunkowo
Zakładaj, że dostarczanie webhooków odbywa się co najmniej raz (at-least-once) i że utracone potwierdzenia mogą powodować duplikaty. Zduplikuj przed wykonaniem efektów ubocznych, używając stabilnego identyfikatora zdarzenia dostawcy, takiego jak sg_event_id lub svix-id. Wstrzymaj nieidempotentne efekty uboczne do czasu, aż powtarzające się identyfikatory będą bezpiecznie ignorowane.
Pierwsze 15 minut
- Porównaj zduplikowane payloady SendGrid po sg_event_id, gdy to pole jest dołączone.
- Sprawdź odpowiedzi Event Webhook inne niż 2xx, które wyzwalają ponowne próby SendGrid przez maksymalnie 24 godziny.
- Porównaj duplikaty Resend po svix-id i potwierdź, że już przetworzone identyfikatory są pomijane.
Teraz
- Zapisuj i pomijaj powtarzające się wartości sg_event_id lub svix-id przed wykonaniem efektów ubocznych.
Najbliższe 24 godziny
- Uczyń zapisywanie identyfikatora zdarzenia i efekt uboczny jedną idempotentną ścieżką przetwarzania.
Najbliższe 7 dni
- Używaj znacznika czasu zdarzenia dostawcy, gdy stan aplikacji zależy od kolejności zdarzeń, ponieważ Resend nie gwarantuje kolejności dostarczania.
Kontrole techniczne
Inżynieria
- Persist and deduplicate SendGrid sg_event_id values when included.
- Confirm the SendGrid endpoint returns a 2xx response for successful processing so non-2xx retry behavior is not triggered.
- Use the Resend created_at timestamp rather than arrival order when event order must be reconstructed.
Kryteria weryfikacji
- Ponów payloady z tym samym sg_event_id i potwierdź, że efekt uboczny występuje tylko raz.
- Potwierdź, że udane przetwarzanie SendGrid zwraca 2xx i żadna sekwencja ponawiania dla odpowiedzi innych niż 2xx nie jest kontynuowana.
- Ponów zapisany svix-id z Resend i potwierdź, że jest pomijany jako już przetworzony.
Kryteria eskalacji
- Eskaluj wewnętrznie, gdy powtarzające się sg_event_id nie jest pomijane i wykonuje efekt uboczny po włączeniu lokalnej deduplikacji.
- Po potwierdzeniu, że zapisany svix-id jest pomijany, a efekt uboczny występuje raz, traktuj dalsze dostarczanie tego identyfikatora jako udokumentowane zachowanie at-least-once, a nie warunek eskalacji.
Zapobieganie
- Traktuj sg_event_id z SendGrid jako klucz deduplikacji, gdy jest dołączony.
- Zapisuj wartości svix-id z Resend i pomijaj już przetworzone identyfikatory.
- Używaj created_at zamiast kolejności nadejścia, gdy kolejność zdarzeń Resend ma znaczenie.
Wpływ na biznes
- Dostarczanie co najmniej raz może powtórzyć efekty uboczne, gdy utracone potwierdzenie spowoduje ponowne dostarczenie tego samego zdarzenia przez dostawcę.
Uwagi dostawcy
- SendGrid ponawia żądania POST Event Webhook po odpowiedziach innych niż 2xx w rosnących odstępach czasu przez maksymalnie 24 godziny.
- Resend zapewnia dostarczanie co najmniej raz i nie gwarantuje kolejności dostarczania.
Otwarte pytania
- Nazwy pól identyfikatorów zdarzeń, harmonogramy ponawiania, narzędzia do ponawiania i gwarancje kolejności różnią się w zależności od ESP i produktu webhook.
- To, czy obecne duplikaty współdzielą ten sam identyfikator zdarzenia dostawcy, czy reprezentują odrębne zdarzenia upstream, wymaga analizy payloadu i bazy danych.
- Czas potwierdzenia i atomowość obecnego handlera w stosunku do efektów ubocznych są nieznane do czasu przejrzenia kodu i transakcji bazy danych.
Źródła (4)
- Twilio SendGrid Event Webhook Overview — Duplicate eventsTwilio SendGrid
- Twilio SendGrid Event Webhook Overview — General troubleshootingTwilio SendGrid
- Managing Webhooks — FAQ: What are the delivery guarantees?Resend
- Managing Webhooks — FAQ: Do events arrive in order?Resend
