Webhooki
Webhooki zapewniają powiadomienia w czasie rzeczywistym, oparte na zdarzeniach, dotyczące krytycznych aktualizacji cyklu życia płatności. Webhooki Cardflo umożliwiają Twoim systemom natychmiastową reakcję na statusy płatności, spory i inne kluczowe zdarzenia.
Automatyzuj przepływy pracy i utrzymuj synchronizację między Twoją platformą a Cardflo bez ciągłego odpytywania.
- Kategoria
- Deweloper
- Możliwości
- 10
- Dostępne na
- Wszystkie plany
Przegląd
Webhooki działają jako asynchroniczne wywołania zwrotne HTTP, które ułatwiają komunikację w czasie rzeczywistym między bramą płatności a serwerem sprzedawcy.
W przeciwieństwie do tradycyjnych metod odpytywania, gdzie serwer wykonuje powtarzające się żądania w celu sprawdzenia aktualizacji statusu, webhooki przesyłają dane do predefiniowanego adresu URL w momencie wystąpienia określonego zdarzenia w cyklu życia płatności.
Ten mechanizm jest kluczowy dla zarządzania zdarzeniami niesynchronicznymi, takimi jak wyniki uwierzytelniania 3-D Secure, asynchroniczne zakończenia alternatywnych metod płatności (APM) lub otrzymanie obciążenia zwrotnego.
W stosie płatności webhooki działają jako tkanka łączna między nabywcą lub PSP a wewnętrznym systemem zarządzania zamówieniami (OMS) sprzedawcy lub platformą zarządzania przychodami. Zapewniają, że późniejsza logika, taka jak blokowanie zapasów lub uprawnienia cyfrowe, pozostaje dokładna bez wprowadzania opóźnień lub niepotrzebnych narzutów API.
Prawidłowa implementacja wymaga solidnego obsługiwania kodów statusu HTTP i idempotencji w celu zarządzania potencjalnymi ponowieniami z serwera wysyłającego, zapewniając, że każde zdarzenie jest przetwarzane raz i tylko raz.
Jak to działa
Zdefiniuj punkt końcowy i zdarzenia
Sprzedawca określa docelowy adres URL w swoim środowisku do odbierania żądań POST. Wybiera konkretne wyzwalacze zdarzeń z cyklu życia płatności, takie jak sukces autoryzacji, inicjacja zwrotu lub utworzenie sporu.
Zapewnia to, że jego system przetwarza tylko odpowiednie pakiety danych, zmniejszając niepotrzebne obciążenie serwera i utrzymując punkty integracji skoncentrowane i łatwe do zarządzania.
Wyzwalacz zdarzeń i ładunek
Gdy nastąpi zmiana statusu, na przykład klient zakończy wyzwanie SCA, system generuje ładunek JSON. Ten ładunek zawiera ustrukturyzowane dane, w tym identyfikator transakcji, identyfikator sprzedawcy (MID), kwotę i konkretny typ zdarzenia.
Brama następnie próbuje dostarczyć te dane do zarejestrowanego punktu końcowego.
Bezpieczeństwo i weryfikacja podpisu
Aby zapobiec nieautoryzowanemu wstrzykiwaniu danych, ładunek jest zazwyczaj podpisywany tajnym kluczem. Serwer sprzedawcy rekonstruuje podpis, używając surowego ciała żądania i porównuje go z nagłówkiem.
Ta weryfikacja zapewnia, że dane pochodzą z zaufanego źródła i nie zostały zmienione podczas przesyłania.
Potwierdź i przetwórz
Serwer sprzedawcy musi niezwłocznie zwrócić kod statusu 200 OK, aby potwierdzić odbiór. Następnie wykonywana jest wewnętrzna logika, taka jak aktualizacja rekordu w bazie danych lub wywołanie automatycznego e-maila.
Jeśli serwer jest offline lub zwraca błąd, system dostarczania postępuje zgodnie z zaprogramowanym harmonogramem ponawiania, aby zapewnić spójność danych.
Dlaczego to ważne
Efektywność operacyjna i automatyzacja
Opieranie się na ręcznych kontrolach statusu lub okresowym odpytywaniu API wprowadza opóźnienia, które mogą pogorszyć doświadczenie użytkownika i opóźnić realizację. Webhooki automatyzują przejście między autoryzacją płatności a dostarczeniem usługi.
Otrzymując natychmiastowe powiadomienia o udanych przechwyceniach lub rozliczeniach, firmy mogą automatyzować przepływy pracy wysyłki, generowanie licencji lub udostępnianie kont, zmniejszając potrzebę ręcznej interwencji i minimalizując ryzyko błędu ludzkiego w zarządzaniu transakcjami.
Zmniejszanie ryzyka i sporów
Powiadomienia o żądaniach pobrania lub obciążeniach zwrotnych pozwalają sprzedawcom reagować w ramach terminów określonych przez system. Natychmiastowe alerty dotyczące miękkich odrzuceń lub awarii SCA umożliwiają proaktywne zaangażowanie klienta.
Reagując na te zdarzenia w miarę ich występowania, sprzedawcy mogą poprawić swoje wskaźniki sukcesu reprezentacji i zmniejszyć koszty operacyjne związane z nierozwiązanymi awariami płatności lub sporami, które w przeciwnym razie mogłyby pozostać niezauważone do czasu okresowego ręcznego audytu.
Zastosowania
Cykl życia subskrypcji i SaaS
Gdy płatność cykliczna nie powiedzie się lub karta wygaśnie, webhook wyzwala zautomatyzowaną sekwencję windykacyjną lub zawiesza dostęp użytkownika, utrzymując dokładne cykle rozliczeniowe bez ręcznego nadzoru.
Realizacja zamówień e-commerce
Sprzedawca internetowy używa webhooków do zwolnienia towarów do wysyłki dopiero po otrzymaniu zdarzenia „capture. succeeded”, zapobiegając wysyłce przedmiotów, dla których płatność nie została w pełni autoryzowana.
Koordynacja wypłat na rynku
Platformy otrzymujące środki mogą wyzwalać wypłaty dla pod-sprzedawców dopiero po osiągnięciu statusu rozliczonego przez początkową transakcję klienta, zapewniając płynność i zmniejszając ryzyko odwrócenia wypłat.
Finalizacja alternatywnych metod płatności
W przypadku metod takich jak przelewy bankowe lub lokalne schematy, które nie zapewniają natychmiastowego potwierdzenia, webhooki powiadamiają system godziny lub dni później, gdy środki zostaną potwierdzone.
W liczbach
Typowe opóźnienie branżowe między zarejestrowaniem zdarzenia na platformie nabywczej a wysłaniem webhooka do punktu końcowego sprzedawcy.
Standardowy wskaźnik niezawodności dla usług webhook, uwzględniający automatyczną logikę ponawiania i redundantną infrastrukturę dostarczania.
Obserwacja branżowa poprawy szybkości realizacji przy przejściu z okresowego przetwarzania wsadowego na architektury webhook oparte na zdarzeniach.
Powiązane pojęcia
Talk to our team about a live rollout on your acquiring stack.
Co zyskujesz dzięki Webhooki
- Asynchroniczne dostarczanie zmian statusu transakcji w celu poprawy wydajności systemu.
- Obsługa wielu typów zdarzeń, w tym autoryzacji, przechwycenia, zwrotu i sporu.
- Nagłówki sygnatur HMAC-SHA256 dla solidnej weryfikacji integralności przychodzących danych.
- Automatyczna logika ponawiania po harmonogramach wykładniczego wycofywania dla nieudanych prób dostarczenia.
- Wersjonowanie ładunku w celu zapewnienia kompatybilności w miarę ewolucji struktur danych.
- Możliwości białej listy IP w celu ograniczenia ruchu przychodzącego do znanych źródeł bramy.
- Włączenie klucza idempotencji w celu zapobiegania duplikowaniu przetwarzania tego samego zdarzenia płatności.
- Szczegółowe dzienniki zdarzeń do debugowania i audytu wydajności dostarczania webhooków w panelu.
- Granularny wybór zdarzeń w celu zminimalizowania zużycia przepustowości i wymagań przetwarzania po stronie serwera.
- Funkcjonalność trybu testowego do walidacji zachowania punktu końcowego w symulowanych scenariuszach płatności.
A short scoping call, then a written plan for your MIDs.
Pytania dotyczące Webhooki
Jak nasz serwer powinien obsługiwać zduplikowane powiadomienia webhook?
Standardową praktyką dla bram płatności jest stosowanie mechanizmu ponawiania, jeśli punkt końcowy nie zwróci odpowiedzi 200 OK w określonym czasie. W konsekwencji Twój serwer może otrzymać to samo zdarzenie wielokrotnie.
Aby zachować integralność danych, należy zaimplementować logikę idempotencji. Zazwyczaj polega to na śledzeniu unikalnego identyfikatora zdarzenia dostarczonego w ładunku i sprawdzaniu, czy został on już przetworzony przed wykonaniem jakiejkolwiek logiki biznesowej.
Jeśli identyfikator istnieje w Twojej bazie danych, Twój serwer powinien zignorować zdarzenie, ale nadal zwrócić 200 OK, aby zatrzymać dalsze ponawianie.
Jaka jest różnica między odpytywaniem API a używaniem webhooków?
Odpytywanie wymaga, aby Twój serwer inicjował częste żądania do bramy w celu sprawdzenia aktualizacji statusu, co jest nieefektywne i może prowadzić do problemów z ograniczeniem szybkości lub opóźnionych informacji. Webhooki odwracają ten przepływ, gdzie brama inicjuje żądanie do Twojego serwera tylko wtedy, gdy wystąpi zdarzenie.
Ten model „push” jest bardziej efektywny, zmniejszając obciążenie serwera i zapewniając aktualizację statusów w czasie zbliżonym do rzeczywistego w całej Twojej infrastrukturze, co jest szczególnie ważne w przypadku działań wrażliwych na czas, takich jak dostarczanie treści cyfrowych lub zapobieganie oszustwom.
Dlaczego weryfikacja podpisu jest konieczna dla każdego żądania webhook?
Ponieważ punkty końcowe webhook są publicznymi adresami URL, są teoretycznie dostępne dla każdej jednostki w Internecie. Bez weryfikacji atakujący mógłby wysłać sfałszowany ładunek JSON do Twojego serwera, fałszywie wskazując, że płatność o wysokiej wartości zakończyła się sukcesem.
Używając wspólnego sekretu do weryfikacji podpisu HMAC dostarczonego w nagłówku żądania, Twój system może matematycznie udowodnić, że wiadomość została wysłana przez Twojego PSP i że zawartość nie została zmieniona, zapewniając bezpieczeństwo procesu realizacji zamówienia.
Jak webhooki obsługują wymagania 3-D Secure i SCA?
Podczas przepływu 3-DS transakcja często przechodzi w stan oczekiwania, podczas gdy użytkownik jest przekierowywany do swojego wystawcy w celu uwierzytelnienia. Ostateczny wynik tego uwierzytelnienia może nie być znany natychmiast.
Webhooki są używane do powiadamiania Twojego systemu, gdy wyzwanie 3-DS zostanie zakończone, a transakcja zostanie następnie autoryzowana lub odrzucona. Zapobiega to zawieszaniu się Twojej kasy i pozwala Twojemu backendowi reagować na ostateczny stan autoryzacji, gdy klient wróci ze strony przekierowania banku.
Czy webhooki mogą być używane do zarządzania terminami obciążeń zwrotnych i sporów?
Tak, webhooki są podstawowym narzędziem do zarządzania cyklem życia sporów. Gdy posiadacz karty inicjuje żądanie pobrania lub formalne obciążenie zwrotne u swojego wystawcy, brama otrzymuje to powiadomienie za pośrednictwem systemów kart.
Następnie do Twojego systemu wysyłany jest webhook określający kod przyczyny, kwotę i termin odpowiedzi. Korzystając z tych danych w czasie rzeczywistym, możesz zautomatyzować zawieszenie odpowiedniego konta i powiadomić swój zespół ryzyka, aby natychmiast rozpoczął proces reprezentacji, zwiększając prawdopodobieństwo pomyślnego odwrócenia sporu.
Co się stanie, jeśli nasz serwer będzie niedostępny podczas krytycznego zdarzenia webhook?
Niezawodne systemy webhook działają z polityką ponawiania. Jeśli Twój punkt końcowy zwróci błąd 4xx lub 5xx, lub nie odpowie w ciągu kilku sekund, brama umieści wiadomość w kolejce do ponownego dostarczenia.
Te ponowienia zazwyczaj podążają za wzorcem wykładniczego wycofywania, próbując dostarczyć wiadomość kilka razy w ciągu minut lub godzin.
Aby zapewnić długoterminową spójność, powinieneś również mieć mechanizm awaryjny, taki jak codzienny skrypt uzgadniania, który wywołuje API w celu znalezienia wszelkich pominiętych zmian statusu, zapewniając siatkę bezpieczeństwa w przypadku dłuższych przestojów.
Powiązane funkcje.
Gotowy na prędkość?
Opowiedz nam o swojej firmie. Dobierzemy dla Ciebie odpowiednich partnerów aktywizujących i właściwą ścieżkę, zazwyczaj w ciągu tygodnia.