Webhooky
Webhooky poskytují real-time, událostmi řízená oznámení o kritických aktualizacích životního cyklu plateb. Webhooky Cardflo umožňují vašim systémům okamžitě reagovat na stavy plateb, spory a další klíčové události.
Automatizujte pracovní postupy a udržujte synchronizaci mezi vaší platformou a Cardflo bez neustálého dotazování.
- Kategorie
- Vývojář
- Schopnosti
- 10
- Dostupné na
- Všechny plány
Přehled
Webhooky fungují jako asynchronní HTTP callbacky, které usnadňují komunikaci v reálném čase mezi platební bránou a serverem obchodníka.
Na rozdíl od tradičních metod dotazování (pollingu), kdy server provádí opakované požadavky na kontrolu aktualizací stavu, webhooky odesílají data na předdefinovanou URL adresu v okamžiku, kdy dojde k určité události v rámci platebního životního cyklu.
Tento mechanismus je klíčový pro správu nesynchronních událostí, jako jsou výsledky ověření 3-D Secure, dokončení asynchronních alternativních platebních metod (APM) nebo obdržení chargebacku.
V rámci platebního stacku fungují webhooky jako propojovací tkáň mezi akceptantem nebo PSP a interním systémem pro správu objednávek (OMS) nebo platformou pro správu příjmů obchodníka.
Zajišťují, že následná logika, jako je zamykání inventáře nebo digitální nárok, zůstane přesná, aniž by došlo k latenci nebo zbytečné režii API.
Správná implementace vyžaduje robustní zpracování stavových kódů HTTP a idempotence pro správu potenciálních opakování ze strany odesílajícího serveru, čímž se zajišťuje, že každá událost je zpracována jednou a pouze jednou.
Jak to funguje
Definujte koncový bod a události
Obchodník specifikuje v rámci svého prostředí cílovou URL adresu pro příjem požadavků POST. Vybere konkrétní spouštěče událostí z životního cyklu platby, jako je úspěšná autorizace, zahájení vrácení peněz nebo vytvoření sporu.
Tím se zajišťuje, že jeho systém zpracovává pouze relevantní datové pakety, čímž se snižuje nepotřebné zatížení serveru a body integrace zůstávají zaměřené a spravovatelné.
Spuštění události a datová zpráva
Když dojde ke změně stavu, například když zákazník dokončí výzvu SCA, systém vygeneruje JSON datovou zprávu. Tato datová zpráva obsahuje strukturovaná data, včetně ID transakce, ID obchodníka (MID), částky a konkrétního typu události.
Brána se poté pokusí doručit tato data na zaregistrovaný koncový bod.
Zabezpečení a ověření podpisu
K zamezení neoprávněného vkládání dat je datová zpráva obvykle podepsána tajným klíčem. Server obchodníka rekonstruuje podpis pomocí nezpracovaného těla požadavku a porovnává jej s hlavičkou.
Toto ověření zajišťuje, že data pocházejí z důvěryhodného zdroje a nebyla během přenosu pozměněna.
Potvrdit a zpracovat
Server obchodníka musí okamžitě vrátit stavový kód 200 OK, aby potvrdil přijetí. Interní logika poté provede akci, například aktualizuje záznam v databázi nebo spustí automatický e-mail.
Pokud je server offline nebo vrátí chybu, doručovací systém se řídí naprogramovaným plánem opakování, aby zajistil konzistenci dat.
Proč na tom záleží
Provozní efektivita a automatizace
Spoléhání se na ruční kontroly stavu nebo periodické dotazování API zavádí latenci, která může zhoršit uživatelskou zkušenost a zpozdit plnění. Webhooky automatizují přechod mezi autorizací platby a dodávkou služeb.
Přijímáním okamžitých oznámení o úspěšných zachyceních nebo vypořádání mohou podniky automatizovat pracovní postupy expedice, generování licencí nebo zřizování účtů, čímž se snižuje potřeba manuálního zásahu a minimalizuje se riziko lidské chyby při správě transakcí.
Snížení rizika a řešení sporů
Oznámení o žádostech o stažení nebo chargebackech umožňují obchodníkům reagovat v časových rámcích stanovených schématem. Okamžitá upozornění na soft declines nebo selhání SCA umožňují proaktivní zapojení zákazníků.
Reakcí na tyto události v okamžiku, kdy nastanou, mohou obchodníci zlepšit míru úspěšnosti svého zastupování a snížit provozní náklady spojené s neřešenými platebními selháními nebo spory, které by jinak mohly zůstat nepovšimnuty až do pravidelného manuálního auditu.
Případy použití
Životní cyklus předplatného a SaaS
Když opakovaná platba selže nebo vyprší platnost karty, webhook spustí automatizovanou sekvenci upomínek nebo pozastaví přístup uživatele, čímž udržuje přesné fakturační cykly bez ručního dohledu.
Plnění objednávek e-commerce
Online prodejce používá webhooky k uvolnění zboží k expedici teprve poté, co obdrží událost „capture. succeeded“, čímž zabrání expedici položek, u nichž platba nebyla plně autorizována.
Koordinace výplat na tržišti
Platformy přijímající finanční prostředky mohou spouštět výplaty subobchodníkům pouze poté, co počáteční zákaznická transakce dosáhne stavu „vypořádáno“, čímž je zajištěna likvidita a snižuje se riziko zrušení výplaty.
Finalizace alternativní platební metody
U metod, jako jsou bankovní převody nebo místní schémata, které neposkytují okamžité potvrzení, webhooky oznámí systému hodiny nebo dny později, kdy jsou prostředky potvrzeny.
V číslech
Typické průmyslové zpoždění mezi záznamem události v platformě akceptanta a odesláním webhooku na koncový bod obchodníka.
Standardní benchmark spolehlivosti pro služby webhooků při zahrnutí automatické logiky opakování a redundantní doručovací infrastruktury.
Průmyslové pozorování zlepšení rychlosti plnění při přechodu z periodického dávkového zpracování na architektury webhooků řízené událostmi.
Související pojmy
Talk to our team about a live rollout on your acquiring stack.
What you get with Webhooky
- Asynchronní doručování změn stavu transakcí pro zlepšení výkonu systému.
- Podpora více typů událostí, včetně autorizace, zachycení, vrácení peněz a sporu.
- HMAC-SHA256 hlavičky podpisu pro robustní ověření integrity příchozích dat.
- Automatická logika opakování s exponenciálním zpětným zpožděním pro neúspěšné pokusy o doručení.
- Verzování datové zprávy pro zajištění kompatibility, jak se datové struktury vyvíjejí.
- Možnosti povolování IP adres pro omezení příchozího provozu na známé zdroje brány.
- Zahrnutí klíče idempotence pro zabránění duplicitním zpracováním stejné platební události.
- Podrobné protokoly událostí pro ladění a audit výkonu doručení webhooků v rámci řídicího panelu.
- Granulární výběr událostí pro minimalizaci využití šířky pásma a požadavků na zpracování na straně serveru.
- Funkce testovacího režimu pro ověřování chování koncového bodu se simulovanými platebními scénáři.
A short scoping call, then a written plan for your MIDs.
Questions about Webhooky
Jak by měl náš server zpracovávat duplicitní notifikace webhooků?
Je standardní praxí, aby platební brány používaly mechanismus opakování, pokud koncový bod nevrátí odpověď 200 OK v konkrétním časovém rámci. V důsledku toho může váš server obdržet stejnou událost vícekrát.
Pro udržení integrity dat byste měli implementovat logiku idempotence. To obvykle zahrnuje sledování jedinečného ID události poskytnutého v záhlaví a kontrolu, zda již bylo zpracováno před spuštěním jakékoli obchodní logiky.
Pokud ID existuje ve vaší databázi, váš server by měl událost ignorovat, ale přesto vrátit 200 OK, aby zastavil další pokusy o opakování.
Jaký je rozdíl mezi dotazováním API a používáním webhooků?
Dotazování vyžaduje, aby váš server inicioval časté požadavky na bránu pro kontrolu aktualizací stavu, což je neefektivní a může vést k problémům s omezením rychlosti (rate-limiting) nebo zpožděným informacím.
Webhooky tento tok obrací, kdy brána iniciuje požadavek na váš server pouze tehdy, když dojde k události.
Tento model „push“ je efektivnější, snižuje zatížení serveru a zajišťuje, že stavy jsou aktualizovány téměř v reálném čase napříč vaší infrastrukturou, což je obzvláště důležité pro časově citlivé akce, jako je doručování digitálního obsahu nebo prevence podvodů.
Proč je ověření podpisu nutné pro každý požadavek webhooku?
Jelikož koncové body webhooků jsou veřejné URL adresy, jsou teoreticky přístupné jakékoli entitě na internetu. Bez ověření by útočník mohl na váš server poslat podvržený JSON payload, který by falešně indikoval, že platba s vysokou hodnotou byla úspěšná.
Použitím sdíleného tajemství k ověření podpisu HMAC poskytnutého v hlavičce požadavku může váš systém matematicky dokázat, že zpráva byla odeslána vaším PSP a že obsah nebyl během přenosu pozměněn, čímž je zajištěna bezpečnost vašeho procesu plnění objednávek.
Jak webhooky zpracovávají požadavky 3-D Secure a SCA?
Během toku 3-DS se transakce často přesune do stavu čekání, zatímco uživatel je přesměrován k vydavateli pro ověření. Konečný výsledek tohoto ověření nemusí být okamžitě znám.
Webhooky se používají k oznámení vašeho systému, když je výzva 3-DS dokončena a transakce je následně autorizována nebo zamítnuta. Tím se zabrání zablokování vaší pokladny a umožní vašemu backendu reagovat na konečný stav autorizace, jakmile se zákazník vrátí z přesměrovací stránky banky.
Lze webhooky použít ke správě časových os chargebacků a sporů?
Ano, webhooky jsou primárním nástrojem pro správu životního cyklu sporů. Když držitel karty iniciuje požadavek na zrušení transakce (Retrieval Request) nebo formální chargeback u svého vydavatele, platební brána obdrží toto oznámení prostřednictvím karetních schémat.
Poté je do vašeho systému odeslán webhook specifikující kód důvodu, částku a termín pro odpověď. Použitím těchto dat v reálném čase můžete automatizovat pozastavení příslušného účtu a upozornit svůj rizikový tým, aby okamžitě zahájil proces zastupování, čímž se zvýší pravděpodobnost úspěšného zrušení sporu.
Co se stane, když náš server vypadne během kritické události webhooku?
Spolehlivé webhook systémy fungují s politikou opakování. Pokud váš koncový bod vrátí chybu 4xx nebo 5xx, nebo neodpoví během několika sekund, brána zprávu zařadí do fronty pro opětovné doručení.
Tyto opakování obvykle následují exponenciální zpožďovací vzorec, pokoušející se o doručení několikrát během minut nebo hodin.
Aby byla zajištěna dlouhodobá konzistence, měli byste mít také záložní mechanismus, jako je denní skript pro odsouhlasení, který volá API pro nalezení všech zmeškaných změn stavu, čímž poskytuje bezpečnostní síť pro delší výpadky.
Související funkce.
Připraveni na rychlost?
Řekněte nám o svém podnikání. Spojíme vás s těmi správnými akvizičními partnery a správnou cestou, obvykle do týdne.