Webhooks
Webhooks tillhandahåller realtidsbaserade, händelsestyrda aviseringar för kritiska uppdateringar i betalningslivscykeln. Cardflos webhooks gör det möjligt för dina system att reagera omedelbart på betalningsstatusar, tvister och andra viktiga händelser.
Automatisera arbetsflöden och upprätthåll synkronisering mellan din plattform och Cardflo utan ständig polling.
- Kategori
- Utvecklare
- Funktioner
- 10
- Tillgänglig på
- Alla planer
Översikten
Webhooks fungerar som asynkrona HTTP-callbacks som underlättar realtidskommunikation mellan en betalningsgateway och en handlarserver.
Till skillnad från traditionella pollingmetoder där en server gör repetitiva förfrågningar för att kontrollera statusuppdateringar, skickar webhooks data till en fördefinierad URL i samma ögonblick som en specifik händelse inträffar inom betalningslivscykeln.
Denna mekanism är avgörande för att hantera icke-synkrona händelser som 3-D Secure-autentiseringsresultat, asynkrona slutföranden av alternativa betalningsmetoder (APM) eller mottagandet av en chargeback. Inom betalningsstacken fungerar webhooks som den sammanlänkande vävnaden mellan förvärvaren eller PSP och handlarens interna orderhanteringssystem (OMS) eller intäktshanteringsplattform.
De säkerställer att efterföljande logik, såsom inventarielåsning eller digital rättighet, förblir korrekt utan att införa latens eller onödig API-overhead.
Korrekt implementering kräver robust hantering av HTTP-statuskoder och idempotens för att hantera potentiella återförsök från den sändande servern, vilket säkerställer att varje händelse bearbetas en gång och endast en gång.
Så fungerar det
Definiera slutpunkt och händelser
En handlare specificerar en destinations-URL inom sin miljö för att ta emot POST-förfrågningar. De väljer specifika händelseutlösare från betalningslivscykeln, såsom auktorisationsframgång, återbetalningsinitiering eller tvistupprättande.
Detta säkerställer att deras system endast bearbetar relevanta datapaket, vilket minskar onödig serverbelastning och håller integrationspunkterna fokuserade och hanterbara.
Händelseutlösare och nyttolast
När en statusändring inträffar, till exempel att en kund slutför en SCA-utmaning, genererar systemet en JSON-nyttolast. Denna nyttolast innehåller strukturerad data, inklusive transaktions-ID, Merchant ID (MID), belopp och den specifika händelsetypen.
Gatewayen försöker sedan leverera denna data till den registrerade slutpunkten.
Säkerhet och signaturverifiering
För att förhindra obehörig datainmatning signeras nyttolasten vanligtvis med en hemlig nyckel. Handlarservern rekonstruerar signaturen med hjälp av den råa förfrågningskroppen och jämför den med huvudet.
Denna verifiering säkerställer att data kom från den betrodda källan och inte manipulerades under överföringen.
Bekräfta och bearbeta
Handlarservern måste omedelbart returnera en 200 OK-statuskod för att bekräfta mottagandet. Intern logik utförs sedan, såsom att uppdatera en databaspost eller utlösa ett automatiserat e-postmeddelande.
Om servern är offline eller returnerar ett fel, följer leveranssystemet ett programmerat återförsöksschema för att säkerställa datakonsistens.
Varför det spelar roll
Operativ effektivitet och automatisering
Att förlita sig på manuella statuskontroller eller periodisk API-polling introducerar latens som kan försämra användarupplevelsen och fördröja uppfyllandet. Webhooks automatiserar övergången mellan betalningsauktorisation och tjänsteleverans.
Genom att få omedelbar avisering om framgångsrika infånganden eller avräkningar kan företag automatisera fraktarbetsflöden, licensgenerering eller kontoprovisionering, vilket minskar behovet av manuell intervention och minimerar risken för mänskliga fel i transaktionshanteringen.
Risk- och tvistreducering
Aviseringar om återkravsförfrågningar eller chargebacks gör det möjligt för handlare att svara inom systemets tidsfrister. Omedelbara varningar om mjuka avslag eller SCA-fel möjliggör proaktivt kundengagemang.
Genom att reagera på dessa händelser när de inträffar kan handlare förbättra sina framgångsfrekvenser för representering och minska de operativa kostnaderna i samband med obehandlade betalningsfel eller tvister som annars kanske hade gått obemärkta förbi fram till en periodisk manuell granskning.
Användningsfall
Prenumerations- och SaaS-livscykel
När en återkommande betalning misslyckas eller ett kort går ut, utlöser en webhook en automatiserad påminnelseföljd eller avbryter användarens åtkomst, vilket upprätthåller korrekta faktureringscykler utan manuell övervakning.
E-handelsorderuppfyllnad
En onlinehandlare använder webhooks för att frigöra varor för frakt först efter att ha mottagit en 'capture. succeeded'-händelse, vilket förhindrar utskick av varor för vilka betalning inte har auktoriserats fullt ut.
Marknadsplatsutbetalningskoordinering
Plattformar som tar emot medel kan utlösa utbetalningar till underhandlare först efter att den initiala kundtransaktionen har uppnått en avräknad status, vilket säkerställer likviditet och minskar risken för utbetalningsåterföringar.
Slutförande av alternativa betalningsmetoder
För metoder som banköverföringar eller lokala system som inte ger omedelbar bekräftelse, meddelar webhooks systemet timmar eller dagar senare när medel bekräftas.
I siffror
Typisk branschfördröjning mellan att en händelse registreras i förvärvsplattformen och att webhooken skickas till handlarens slutpunkt.
Standardtillförlitlighetsmått för webhook-tjänster när automatisk återförsökslogik och redundant leveransinfrastruktur inkluderas.
Branschens observation av förbättring i uppfyllnadshastighet vid övergång från periodisk batchbearbetning till händelsestyrda webhook-arkitekturer.
Relaterade termer
Talk to our team about a live rollout on your acquiring stack.
Vad du får med Webhooks
- Asynkron leverans av transaktionsstatusändringar för förbättrad systemprestanda.
- Stöd för flera händelsetyper inklusive auktorisation, infångande, återbetalning och tvist.
- HMAC-SHA256-signaturhuvuden för robust verifiering av inkommande dataintegritet.
- Automatisk återförsökslogik enligt exponentiella backoff-scheman för misslyckade leveransförsök.
- Payload-versionshantering för att säkerställa kompatibilitet när datastrukturer utvecklas över tid.
- IP-vitlistningsfunktioner för att begränsa inkommande trafik till kända gateway-källor.
- Inkludering av idempotensnyckel för att förhindra dubbel bearbetning av samma betalningshändelse.
- Detaljerade händelseloggar för felsökning och granskning av webhook-leveransprestanda inom instrumentpanelen.
- Granulärt händelseval för att minimera bandbreddsanvändning och server-sidans bearbetningskrav.
- Testlägesfunktionalitet för att validera slutpunktsbeteende med simulerade betalningsscenarier.
A short scoping call, then a written plan for your MIDs.
Frågor om Webhooks
Hur ska vår server hantera dubbla webhook-aviseringar?
Det är standardpraxis för betalningsgateways att använda en återförsöksmekanism om en slutpunkt inte returnerar ett 200 OK-svar inom en specifik tidsram. Följaktligen kan din server ta emot samma händelse flera gånger.
För att upprätthålla dataintegritet bör du implementera idempotenslogik. Detta innebär vanligtvis att spåra det unika händelse-ID som tillhandahålls i nyttolasten och kontrollera om det redan har bearbetats innan någon affärslogik utförs.
Om ID:t finns i din databas bör din server ignorera händelsen men ändå returnera ett 200 OK för att stoppa ytterligare återförsök.
Vad är skillnaden mellan att polla ett API och att använda webhooks?
Polling kräver att din server initierar frekventa förfrågningar till gatewayen för att kontrollera statusuppdateringar, vilket är ineffektivt och kan leda till problem med hastighetsbegränsning eller försenad information. Webhooks vänder på detta flöde, där gatewayen initierar en förfrågan till din server endast när en händelse inträffar.
Denna 'push'-modell är effektivare, minskar serverbelastningen och säkerställer att statusar uppdateras i nära realtid över din infrastruktur, vilket är särskilt viktigt för tidskänsliga åtgärder som leverans av digitalt innehåll eller bedrägeribekämpning.
Varför är signaturverifiering nödvändig för varje webhook-förfrågan?
Eftersom webhook-slutpunkter är offentliga URL:er är de teoretiskt tillgängliga för alla enheter på internet. Utan verifiering skulle en angripare kunna skicka en förfalskad JSON-nyttolast till din server, vilket felaktigt indikerar att en betalning med högt värde lyckades.
Genom att använda en delad hemlighet för att verifiera HMAC-signaturen som tillhandahålls i förfrågningshuvudet kan ditt system matematiskt bevisa att meddelandet skickades av din PSP och att innehållet inte har ändrats, vilket säkerställer säkerheten för din orderuppfyllnadsprocess.
Hur hanterar webhooks 3-D Secure- och SCA-krav?
Under ett 3-DS-flöde går transaktionen ofta in i ett väntande tillstånd medan användaren omdirigeras till sin utfärdare för autentisering. Det slutliga resultatet av denna autentisering kanske inte är känt omedelbart.
Webhooks används för att meddela ditt system när 3-DS-utmaningen är slutförd och transaktionen därefter auktoriseras eller nekas. Detta förhindrar att din kassa hänger sig och gör att din backend kan reagera på det slutliga auktorisationstillståndet när kunden återvänder från bankens omdirigeringssida.
Kan webhooks användas för att hantera tidslinjer för chargeback och tvister?
Ja, webhooks är ett primärt verktyg för att hantera tvistlivscykeln. När en kortinnehavare initierar en återkravsförfrågan eller en formell chargeback med sin utfärdare, tar gatewayen emot denna avisering via kortsystemen.
En webhook skickas sedan till ditt system som specificerar orsakskoden, beloppet och tidsfristen för svar. Med hjälp av denna realtidsdata kan du automatisera avstängningen av det relevanta kontot och meddela ditt riskteam att omedelbart påbörja representeringsprocessen, vilket ökar sannolikheten för en framgångsrik tviståterföring.
Vad händer om vår server är nere under en kritisk webhook-händelse?
Pålitliga webhook-system fungerar med en återförsöksprincip. Om din slutpunkt returnerar ett 4xx- eller 5xx-fel, eller inte svarar inom några sekunder, kommer gatewayen att köa meddelandet för återleverans.
Dessa återförsök följer vanligtvis ett exponentiellt backoff-mönster, och försöker leverera flera gånger under minuter eller timmar.
För att säkerställa långsiktig konsekvens bör du också ha en reservmekanism, till exempel ett dagligt avstämningsskript som anropar API:et för att hitta eventuella missade statusändringar, vilket ger ett skyddsnät för längre avbrott.
Relaterade funktioner.
Redo för fart?
Berätta om ditt företag. Vi matchar dig med rätt inlösenpartners och rätt rutt, vanligtvis inom en vecka.