Zdarzenie
Zapis zmiany płatności, sesji gry, weryfikacji KYC, bonusu, profilu gracza lub innego obiektu.
Dokumentacja / Webhooki
Webhooki i dostarczanie zdarzeń
Skonfiguruj niezawodne przekazywanie statusów i zdarzeń między systemami: od utworzenia komunikatu i weryfikacji podpisu po potwierdzenie odbioru, ponowne dostarczanie i kontrolę błędów.
Zdarzenia
statusy i zmiany
Podpis
weryfikacja autentyczności
Ponowienia
ponowne dostarczanie
Kontrola
historia i diagnostyka
Ścieżka zdarzenia
Od utworzenia do potwierdzenia
01
Utworzyć zdarzenie
Wskazać identyfikator, typ, czas, obiekt, status i powiązane dane.
02
Podpisać i wysłać
Przesłać zdarzenie przez HTTPS z podpisem i ograniczonym czasem oczekiwania.
03
Potwierdzić odbiór
Po weryfikacji zapisać zdarzenie i szybko zwrócić pomyślną odpowiedź HTTP.
04
Ponowić przy błędzie
Ponawiać dostarczanie ze zwiększaniem odstępu i zachowywać niewysłane zdarzenia do analizy.
Przegląd
Webhook informuje o zmianie stanu
Nadawca może ponowić dostarczenie, dlatego odbiorca powinien zweryfikować źródło, potwierdzić odbiór i zastosować każde zdarzenie tylko raz.
Potwierdzenie
Odbiorca zwraca pomyślną odpowiedź HTTP po weryfikacji i niezawodnym zapisaniu zdarzenia.
Odzyskiwanie
Ponowne wysłanie i uzgodnienie pomagają odtworzyć dane po czasowej niedostępności jednego z systemów.
Struktura zdarzenia
Jakie dane powinno zawierać zdarzenie
Wspólna struktura komunikatu upraszcza weryfikację, routing, ochronę przed ponowieniami i obsługę różnych typów zdarzeń.
Identyfikator zdarzenia
Unikalna wartość, dzięki której system rozpoznaje ponowne dostarczenie i znajduje historię przetwarzania.
Typ zdarzenia
Jasna i stabilna nazwa określająca, jaka zmiana zaszła i jak ją przetworzyć.
Czas utworzenia
Data i czas utworzenia zdarzenia w uzgodnionym formacie i strefie czasowej.
Powiązany obiekt
Typ i identyfikator płatności, gracza, rundy, wniosku, bonusu lub innego obiektu.
Wersja struktury
Numer wersji pomaga bezpiecznie zmieniać skład komunikatu bez naruszania działających integracji.
Powiązanie z operacją
Identyfikator pierwotnego żądania, transakcji, sesji lub łańcucha powiązanych działań.
Kontekst
Marka, projekt, rynek, środowisko, dostawca i inne dane potrzebne do prawidłowego routingu.
Dane zdarzenia
Minimalny zestaw pól potrzebnych do obsłużenia zmiany lub późniejszego zapytania do API.
Podpis i weryfikacja
Weryfikacja autentyczności i integralności zdarzenia
Przed zmianą danych odbiorca sprawdza bezpieczne połączenie, podpis, czas utworzenia i unikalny identyfikator zdarzenia.
01
Odebrać oryginalny komunikat
Weryfikuj podpis na podstawie pierwotnej treści żądania przed zmianą formatu JSON.
02
Sprawdzić czas
Odrzucaj żądanie, jeżeli czas zdarzenia wykracza poza dopuszczalny przedział.
03
Sprawdzić podpis
Użyj uzgodnionego sekretu i algorytmu HMAC lub podpisu cyfrowego.
04
Sprawdzić identyfikator
Upewnij się, że zdarzenie nie zostało jeszcze zastosowane, i zapisz wynik weryfikacji.
Dostarczanie i ponowienia
Odpowiedzi HTTP i ponowne dostarczanie
Nadawca powinien rozróżniać poprawny odbiór, błąd tymczasowy i trwałą odmowę, a odbiorca — odpowiadać szybko i jednoznacznie.
Pomyślna odpowiedź HTTP
Potwierdza, że zdarzenie zostało zweryfikowane i niezawodnie zapisane do dalszego przetwarzania.
Ograniczony czas oczekiwania
Nie wykonuj długiego przetwarzania przed odpowiedzią nadawcy — najpierw zapisz zdarzenie.
Ponowne wysłanie
Ponawiaj dostarczanie przy tymczasowym błędzie sieciowym, niedostępności lub braku odpowiedzi.
Zwiększanie odstępu
Stopniowo zwiększaj przerwę między próbami, aby nie tworzyć dodatkowego obciążenia.
Kolejka niewysłanych zdarzeń
Po wyczerpaniu prób zachowaj zdarzenie do diagnostyki i ręcznej obsługi.
Ręczne ponowne wysłanie
Operator może ponownie wysłać wybrane zdarzenie bez tworzenia nowej operacji.
Kontrola dostarczania
Śledź liczbę prób, odpowiedzi, ostatni błąd i czas następnego wysłania.
Powiadomienia
Informuj zespół o wzroście liczby błędów, wyczerpaniu prób i gromadzeniu się zdarzeń w kolejce.
Obsługa zdarzeń
Ochrona przed ponowieniami i kolejność statusów
Odbiorca nie powinien zakładać pojedynczego dostarczenia ani ścisłej kolejności zdarzeń.
Jednorazowe zastosowanie
Zapisywać identyfikator zdarzenia przed zmianą danych.
Potwierdzać ponowne zdarzenie bez ponownego obciążenia, uznania lub zmiany.
Wiązać zdarzenie z obiektem i jego bieżącym stanem.
Zapisywać zdarzenie i zmianę biznesową jako jedną spójną operację.
Kolejność i aktualność
Porównywać czas, numer sekwencji lub wersję zdarzenia.
Nie cofać obiektu do nieaktualnego stanu przy opóźnionym dostarczeniu.
Dopuszczać wyłącznie dozwolone przejścia między statusami.
W razie wątpliwości pobrać aktualny stan obiektu przez API.
Testowanie
Co sprawdzić przed uruchomieniem
Sprawdź pomyślne dostarczenie, nieprawidłowy podpis, ponowienia, wolną odpowiedź, zmianę kolejności zdarzeń i odzyskanie po awarii.
Nieprawidłowy podpis
Zmodyfikowany komunikat, nieznany klucz, przekroczony czas i nieobsługiwany algorytm.
Ponowne dostarczanie
To samo zdarzenie przychodzi kilka razy przed i po zakończeniu przetwarzania.
Wolna odpowiedź
Odbiorca odpowiada zbyt długo, połączenie zostaje przerwane lub potwierdzenie nie dociera do nadawcy.
Naruszenie kolejności
Status końcowy przychodzi przed pośrednim, a stare zdarzenie jest dostarczane po nowym.
Niedostępny adres
Sprawdź błędy HTTP 5xx, DNS, TLS, ograniczenia częstotliwości i pełne wyczerpanie prób.
Historia dostarczania
Według identyfikatora zdarzenia powinny być dostępne wszystkie próby, odpowiedzi, błędy i wynik ręcznego wysłania.
Lista kontrolna przed uruchomieniem
Dostarczanie produkcyjne jest włączane po sprawdzeniu bezpieczeństwa, ochrony przed ponowieniami, ponownego wysyłania i kontroli błędów.
Dla środowiska testowego i produkcyjnego używane są różne adresy i sekrety podpisu.
Podpis jest weryfikowany na podstawie pierwotnego komunikatu z uwzględnieniem czasu utworzenia.
Identyfikator zdarzenia jest zapisywany i chroni operacje przed ponownym wykonaniem.
Odbiorca szybko zwraca pomyślną odpowiedź HTTP po zapisaniu zdarzenia.
Skonfigurowano ponowne próby, zwiększanie odstępu i ręczne wysyłanie.
Historia dostarczania i wyszukiwanie według identyfikatora są dostępne dla zespołu wsparcia.
Chcesz skonfigurować niezawodne dostarczanie zdarzeń?
Przekaż listę zdarzeń, adresy odbioru i zasady zmiany statusów. APIACE pomoże określić strukturę komunikatów, weryfikację podpisu, ponowne dostarczanie i kontrolę błędów.