Zdarzenie nie jest zdalną zmianą pola
Webhook to sposób powiadomienia innego systemu o zdarzeniu. Może informować, że powstało zgłoszenie, zmienił się status albo zatwierdzono ofertę. Odbiorca sam decyduje, jak je przetworzy. Dlatego integracja wymaga więcej niż wpisania adresu serwera w ustawieniach: trzeba ustalić format, tożsamość zdarzenia i znaczenie potwierdzenia odbioru.
W przykładowej firmie szkoleniowej zapis uczestnika na stronie powinien utworzyć sprawę w CRM. Gdy formularz działa poprawnie, ale drugi system chwilowo nie odpowiada, klient nie powinien ponownie wpisywać danych. Potrzebny jest zapis lokalny oraz mechanizm późniejszego przekazania. To pozwala oddzielić przyjęcie zapytania od dostępności każdego narzędzia używanego w firmie.
Zaprojektuj umowę danych
Wiadomość powinna mieć typ zdarzenia, unikalny identyfikator, wersję formatu i odniesienie do właściwego obiektu. Nie przesyłaj całej bazy klienta, jeśli odbiorca potrzebuje tylko numeru sprawy i nowego statusu. Ustal, które pola są wymagane, co oznacza brak wartości i jak obsłużyć nieznaną wersję. Dzięki temu zmiana po jednej stronie nie musi po cichu uszkodzić drugiej.
Sekret nie powinien trafiać do adresu URL. Dokumentacja GitHub opisuje stosowanie sekretu webhooka, HTTPS oraz weryfikacji typu zdarzenia. To przykład zasad bezpiecznego odbioru, a nie identyczny protokół dla każdego dostawcy. Zawsze trzeba sprawdzić dokumentację konkretnej usługi i podpisywać lub weryfikować dokładnie taki materiał, jaki przewiduje.
Potwierdzaj dopiero po bezpiecznym przyjęciu
Odpowiedź potwierdzająca odbiór powinna oznaczać, że system potrafi później dokończyć pracę. Dobrym modelem jest sprawdzenie autentyczności, zapis zdarzenia w trwałej kolejce i szybka odpowiedź, a dopiero potem właściwe przetwarzanie. Długa operacja wykonywana przed potwierdzeniem zwiększa ryzyko przekroczenia limitu dostawcy i ponowienia tego samego zdarzenia.
Przy zapisie danych biznesowych i zamiaru wysyłki pomocny jest wzorzec transactional outbox. Zmiana oraz zapis zdarzenia do wysłania trafiają do jednej transakcji bazy, a oddzielny proces przekazuje wiadomość dalej. AWS opisuje ten wzorzec jako rozwiązanie problemu niespójnego podwójnego zapisu. Nadal trzeba obsłużyć powtórzenia po stronie odbiorcy.
Przyjmij, że zdarzenie może wrócić
Ponowiona dostawa nie powinna tworzyć drugiego klienta ani drugi raz uruchamiać realizacji. Zapisuj identyfikator obsłużonego zdarzenia i wynik operacji w sposób odporny na równoczesne przetwarzanie. Gdy ten sam identyfikator przychodzi z inną treścią, traktuj to jako konflikt wymagający wyjaśnienia, zamiast uznawać nowe dane za niewinną powtórkę.
Jeżeli firma potrzebuje połączenia strony z własnym programem, MyTworzymy.pl realizuje obsługę projektów dla przedsiębiorstw z całej Polski. Warto zacząć od jednego przepływu, na przykład przyjęcia zgłoszenia, i opisać również jego awarie. Integracja jest użyteczna wtedy, gdy wiadomo, co dzieje się po przerwaniu połączenia, nie tylko podczas udanej demonstracji.
Ustal kolejność i właściciela informacji
Zdarzenie „zamknięto sprawę” może dotrzeć przed starszym „rozpoczęto obsługę”. Nie każdy dostawca gwarantuje kolejność między próbami dostarczenia. System powinien znać wersję obiektu albo pobrać jego aktualny stan, jeżeli protokół na to pozwala. Nie nadpisuj nowszej informacji starszą wyłącznie dlatego, że stara wiadomość dotarła później.
Uzgodnij również, gdzie edytuje się poszczególne dane. Jeśli numer telefonu zmienia strona i CRM, potrzebna jest reguła konfliktu. W przeciwnym razie dwukierunkowa synchronizacja może odtwarzać dawną wartość bez końca. Dla pierwszej wersji często rozsądniej wyznaczyć jeden system źródłowy dla określonego pola, a dopiero później rozszerzać możliwości.
Daj administratorowi widok błędów
Kolejka potrzebuje statusów: oczekuje, trwa próba, zakończono i wymaga interwencji. Pokaż ostatni błąd bez sekretów, liczbę prób i czas następnego podejścia. Nie ponawiaj bez końca niepoprawnego formatu, którego kolejna próba nie naprawi. Rozdziel chwilową niedostępność od błędu wymagającego zmiany danych lub konfiguracji.
W projektach omawianych z MyTworzymy.pl warto uwzględnić taki panel w zakresie, zamiast zamawiać sam „most” między usługami. Dla zespołu pracującego z klientami w całej Polsce możliwość sprawdzenia, gdzie utknęło zgłoszenie, bywa ważniejsza niż dodatkowy automatyczny krok. Osoba odpowiedzialna za obsługę potrzebuje czytelnej informacji, nie dostępu do surowego logu programisty.
Przetestuj awarię w połowie operacji
Wyślij ten sam webhook dwa razy, przerwij odpowiedź po zapisaniu danych i zmień kolejność zdarzeń. Sprawdź też niewłaściwy podpis, nieznany typ oraz równoczesne przetwarzanie tej samej dostawy. Idempotencja polega na kontrolowanym zachowaniu przy powtórzeniu operacji; dokumentacja Stripe pokazuje praktyczny model rozpoznawania ponownych żądań przez ich klucz. Nie oznacza to, że każdy interfejs działa identycznie.
Na koniec sprawdź możliwość odtworzenia brakujących zdarzeń po dłuższej awarii. Ustal, jak rozpoznać lukę i porównać stan systemów bez tworzenia duplikatów. Dobra integracja nie tylko przesyła dane, ale daje sposób potwierdzenia, że obie strony znów opisują tę samą sytuację. Bez takiego uzgodnienia błędy mogą pozostawać niewidoczne przez wiele kolejnych dni pracy.
Dokumentację uzupełnij o właściciela kluczy, termin ich przeglądu i procedurę zmiany sekretu. Rotacja nie powinna oznaczać nagłego odrzucania wszystkich wiadomości bez informacji dla obsługi. Zaplanuj moment przełączenia oraz ograniczony okres zgodności, jeśli obsługuje go dostawca. Kontrola integracji obejmuje cały jej cykl życia, nie tylko pierwsze uruchomienie.