Webhook-uri
Webhook-urile oferă notificări în timp real, bazate pe evenimente, pentru actualizări critice ale ciclului de viață al plăților. Webhook-urile Cardflo permit sistemelor dumneavoastră să reacționeze instantaneu la stările plăților, disputelor și altor evenimente cheie.
Automatizați fluxurile de lucru și mențineți sincronizarea între platforma dumneavoastră și Cardflo fără interogări constante.
- Categorie
- Dezvoltator
- Capabilități
- 10
- Disponibil pe
- Toate planurile
Prezentarea generală
Webhook-urile funcționează ca apeluri inverse HTTP asincrone care facilitează comunicarea în timp real între un gateway de plăți și un server comercial.
Spre deosebire de metodele tradiționale de interogare, unde un server face cereri repetitive pentru a verifica actualizările de stare, webhook-urile trimit date către un URL predefinit în momentul în care un eveniment specific are loc în ciclul de viață al plății.
Acest mecanism este critic pentru gestionarea evenimentelor non-sincrone, cum ar fi rezultatele autentificării 3-D Secure, finalizările asincrone ale metodelor de plată alternative (APM) sau primirea unui chargeback.
În cadrul stivei de plăți, webhook-urile acționează ca țesutul conjunctiv între achizitor sau PSP și sistemul intern de gestionare a comenzilor (OMS) al comerciantului sau platforma de gestionare a veniturilor.
Ele asigură că logica ulterioară, cum ar fi blocarea inventarului sau dreptul digital, rămâne exactă fără a introduce latență sau suprasarcină API inutilă.
Implementarea corectă necesită o gestionare robustă a codurilor de stare HTTP și a idempotenței pentru a gestiona potențialele reîncercări de la serverul de trimitere, asigurându-se că fiecare eveniment este procesat o singură dată.
Cum funcționează
Definiți Punctul Final și Evenimentele
Un comerciant specifică un URL de destinație în mediul său pentru a primi cereri POST. El selectează declanșatori de evenimente specifici din ciclul de viață al plății, cum ar fi succesul autorizării, inițierea rambursării sau crearea disputei.
Acest lucru asigură că sistemul său procesează doar pachetele de date relevante, reducând încărcarea inutilă a serverului și menținând punctele de integrare concentrate și gestionabile.
Declanșator de Eveniment și Sarcină Utilă
Atunci când are loc o modificare de stare, cum ar fi finalizarea unei provocări SCA de către un client, sistemul generează o sarcină utilă JSON. Această sarcină utilă conține date structurate, inclusiv ID-ul tranzacției, ID-ul comerciantului (MID), suma și tipul specific de eveniment.
Gateway-ul încearcă apoi să livreze aceste date către punctul final înregistrat.
Securitate și Verificarea Semnăturii
Pentru a preveni injectarea neautorizată de date, sarcina utilă este de obicei semnată cu o cheie secretă. Serverul comerciantului reconstruiește semnătura utilizând corpul cererii brute și o compară cu antetul.
Această verificare asigură că datele au provenit din sursa de încredere și nu au fost modificate în timpul tranzitului.
Confirmare și Procesare
Serverul comerciantului trebuie să returneze prompt un cod de stare 200 OK pentru a confirma primirea. Logica internă se execută apoi, cum ar fi actualizarea unei înregistrări în baza de date sau declanșarea unui e-mail automat.
Dacă serverul este offline sau returnează o eroare, sistemul de livrare urmează un program de reîncercare programat pentru a asigura consistența datelor.
De ce contează
Eficiență Operațională și Automatizare
Bazarea pe verificări manuale ale stării sau interogări API periodice introduce latență care poate degrada experiența utilizatorului și întârzia îndeplinirea. Webhook-urile automatizează tranziția între autorizarea plății și livrarea serviciului.
Prin primirea notificării imediate a capturilor reușite sau a decontării, afacerile pot automatiza fluxurile de lucru de expediere, generarea de licențe sau provizionarea conturilor, reducând necesitatea intervenției manuale și minimizând riscul de eroare umană în gestionarea tranzacțiilor.
Atenuarea Riscurilor și Disputelor
Notificările pentru cererile de recuperare sau chargeback-uri permit comercianților să răspundă în termenele stabilite de schemă. Alertele imediate privind refuzurile ușoare sau eșecurile SCA permit o implicare proactivă a clienților.
Prin reacționarea la aceste evenimente pe măsură ce se întâmplă, comercianții își pot îmbunătăți ratele de succes ale reprezentării și pot reduce costurile operaționale asociate cu eșecurile de plată nerezolvate sau disputele care altfel ar fi putut trece neobservate până la un audit manual periodic.
Cazuri de utilizare
Ciclul de Viață al Abonamentelor și SaaS
Atunci când o plată recurentă eșuează sau un card expiră, un webhook declanșează o secvență automată de recuperare a datoriilor sau suspendă accesul utilizatorului, menținând ciclurile de facturare precise fără supraveghere manuală.
Îndeplinirea Comenzilor E-commerce
Un comerciant online utilizează webhook-uri pentru a elibera bunurile pentru expediere numai după primirea unui eveniment 'capture. succeeded', prevenind expedierea articolelor pentru care plata nu a fost pe deplin autorizată.
Coordonarea Plăților în Piață
Platformele care primesc fonduri pot declanșa plăți către sub-comercianți numai după ce tranzacția inițială a clientului atinge o stare de decontare, asigurând lichiditatea și reducând riscul de inversare a plăților.
Finalizarea Metodei de Plată Alternative
Pentru metode precum transferurile bancare sau schemele locale care nu oferă confirmare instantanee, webhook-urile notifică sistemul ore sau zile mai târziu când fondurile sunt confirmate.
În cifre
Întârzierea tipică în industrie între înregistrarea unui eveniment în platforma de achiziție și expedierea webhook-ului către punctul final al comerciantului.
Referință standard de fiabilitate pentru serviciile webhook atunci când includ logica de reîncercare automată și infrastructura de livrare redundantă.
Observația industriei privind îmbunătățirea vitezei de îndeplinire la trecerea de la procesarea periodică în loturi la arhitecturi webhook bazate pe evenimente.
Termeni asociați
Talk to our team about a live rollout on your acquiring stack.
Ce obțineți cu Webhook-uri
- Livrarea asincronă a modificărilor stării tranzacțiilor pentru o performanță îmbunătățită a sistemului.
- Suport pentru multiple tipuri de evenimente, inclusiv autorizare, captură, rambursare și dispută.
- Anteturi de semnătură HMAC-SHA256 pentru o verificare robustă a integrității datelor primite.
- Logică de reîncercare automată conform programelor de backoff exponențial pentru încercările de livrare eșuate.
- Versionarea sarcinii utile pentru a asigura compatibilitatea pe măsură ce structurile de date evoluează în timp.
- Capacități de listare albă IP pentru a restricționa traficul de intrare la surse de gateway cunoscute.
- Includerea cheii de idempotență pentru a preveni procesarea duplicată a aceluiași eveniment de plată.
- Jurnale detaliate de evenimente pentru depanarea și auditarea performanței livrării webhook-urilor în cadrul tabloului de bord.
- Selecție granulară a evenimentelor pentru a minimiza utilizarea lățimii de bandă și cerințele de procesare pe partea de server.
- Funcționalitate mod de testare pentru validarea comportamentului punctului final cu scenarii de plată simulate.
A short scoping call, then a written plan for your MIDs.
Întrebări despre Webhook-uri
Cum ar trebui să gestioneze serverul nostru notificările webhook duplicate?
Este o practică standard pentru gateway-urile de plată să utilizeze un mecanism de reîncercare dacă un punct final nu returnează un răspuns 200 OK într-un anumit interval de timp. În consecință, serverul dumneavoastră poate primi același eveniment de mai multe ori.
Pentru a menține integritatea datelor, ar trebui să implementați o logică de idempotență. Aceasta implică de obicei urmărirea ID-ului unic al evenimentului furnizat în sarcină utilă și verificarea dacă a fost deja procesat înainte de a executa orice logică de afaceri.
Dacă ID-ul există în baza dumneavoastră de date, serverul dumneavoastră ar trebui să ignore evenimentul, dar să returneze totuși un 200 OK pentru a opri reîncercările ulterioare.
Care este diferența dintre interogarea unui API și utilizarea webhook-urilor?
Interogarea necesită ca serverul dumneavoastră să inițieze cereri frecvente către gateway pentru a verifica actualizările de stare, ceea ce este ineficient și poate duce la probleme de limitare a ratei sau la informații întârziate.
Webhook-urile inversează acest flux, unde gateway-ul inițiază o cerere către serverul dumneavoastră numai atunci când are loc un eveniment.
Acest model 'push' este mai eficient, reducând încărcarea serverului și asigurând că stările sunt actualizate aproape în timp real în întreaga infrastructură, ceea ce este deosebit de important pentru acțiuni sensibile la timp, cum ar fi livrarea de conținut digital sau prevenirea fraudei.
De ce este necesară verificarea semnăturii pentru fiecare cerere webhook?
Deoarece punctele finale webhook sunt URL-uri publice, ele sunt teoretic accesibile de către orice entitate de pe internet.
Fără verificare, un atacator ar putea trimite o sarcină utilă JSON falsificată către serverul dumneavoastră, indicând în mod fals că o plată de mare valoare a fost reușită.
Prin utilizarea unei chei secrete pentru a verifica semnătura HMAC furnizată în antetul cererii, sistemul dumneavoastră poate demonstra matematic că mesajul a fost trimis de PSP-ul dumneavoastră și că conținutul nu a fost modificat, asigurând securitatea procesului dumneavoastră de îndeplinire a comenzilor.
Cum gestionează webhook-urile cerințele 3-D Secure și SCA?
În timpul unui flux 3-DS, tranzacția intră adesea într-o stare de așteptare în timp ce utilizatorul este redirecționat către emitentul său pentru autentificare. Rezultatul final al acestei autentificări poate să nu fie cunoscut imediat.
Webhook-urile sunt utilizate pentru a notifica sistemul dumneavoastră când provocarea 3-DS este finalizată și tranzacția este ulterior autorizată sau refuzată.
Acest lucru împiedică blocarea procesului de plată și permite backend-ului dumneavoastră să reacționeze la starea finală de autorizare odată ce clientul revine de pe pagina de redirecționare a băncii.
Pot fi utilizate webhook-urile pentru a gestiona termenele limită pentru chargeback și dispute?
Da, webhook-urile sunt un instrument principal pentru gestionarea ciclului de viață al disputelor. Atunci când un deținător de card inițiază o cerere de recuperare sau un chargeback formal cu emitentul său, gateway-ul primește această notificare prin schemele de carduri.
Un webhook este apoi trimis către sistemul dumneavoastră, specificând codul motivului, suma și termenul limită de răspuns.
Utilizând aceste date în timp real, puteți automatiza suspendarea contului relevant și puteți notifica echipa dumneavoastră de risc să înceapă imediat procesul de reprezentare, crescând probabilitatea unei inversări reușite a disputei.
Ce se întâmplă dacă serverul nostru este oprit în timpul unui eveniment webhook critic?
Sistemele webhook fiabile operează cu o politică de reîncercare. Dacă punctul dumneavoastră final returnează o eroare 4xx sau 5xx, sau nu răspunde în câteva secunde, gateway-ul va pune mesajul în coadă pentru re-livrare.
Aceste reîncercări urmează de obicei un model de backoff exponențial, încercând livrarea de mai multe ori pe parcursul a minute sau ore.
Pentru a asigura o consistență pe termen lung, ar trebui să aveți și un mecanism de rezervă, cum ar fi un script de reconciliere zilnică care apelează API-ul pentru a găsi orice modificări de stare ratate, oferind o plasă de siguranță pentru întreruperi prelungite.
Funcționalități similare.
Ești pregătit pentru viteză?
Spuneți-ne despre afacerea dvs. Vă vom potrivi cu partenerii de achiziție potriviți și cu ruta corectă, de obicei în mai puțin de o săptămână.