Webhooks
Webhooks leverer realtids, hændelsesdrevne notifikationer for kritiske opdateringer i betalingslivscyklussen. Cardflos webhooks gør det muligt for dine systemer at reagere øjeblikkeligt på betalingsstatusser, tvister og andre nøglehændelser.
Automatiser arbejdsgange og oprethold synkronisering mellem din platform og Cardflo uden konstant polling.
- Kategori
- Udvikler
- Funktioner
- 10
- Tilgængelig på
- Alle abonnementer
Overblikket
Webhooks fungerer som asynkrone HTTP-callbacks, der letter realtidskommunikation mellem en betalingsgateway og en forhandlerserver.
I modsætning til traditionelle polling-metoder, hvor en server foretager gentagne anmodninger for at kontrollere statusopdateringer, skubber webhooks data til en foruddefineret URL i det øjeblik en specifik hændelse opstår inden for betalingslivscyklussen.
Denne mekanisme er afgørende for at administrere ikke-synkrone hændelser såsom 3-D Secure-godkendelsesresultater, asynkrone Alternative Payment Method (APM)-afslutninger eller modtagelse af en chargeback. Inden for betalingsstakken fungerer webhooks som det forbindende væv mellem erhververen eller PSP'en og forhandlerens interne ordrestyringssystem (OMS) eller indtægtsstyringsplatform.
De sikrer, at efterfølgende logik, såsom lagerlåsning eller digital rettighed, forbliver nøjagtig uden at introducere latenstid eller unødvendig API-overhead.
Korrekt implementering kræver robust håndtering af HTTP-statuskoder og idempotens for at administrere potentielle genforsøg fra den afsendende server, hvilket sikrer, at hver hændelse behandles én gang og kun én gang.
Sådan fungerer det
Definer Endpoint og Hændelser
En forhandler specificerer en destinations-URL inden for deres miljø for at modtage POST-anmodninger. De vælger specifikke hændelsestrigger fra betalingslivscyklussen, såsom godkendelsessucces, refusionsinitiering eller tvistoprettelse.
Dette sikrer, at deres system kun behandler relevante datapakker, hvilket reducerer unødvendig serverbelastning og holder integrationspunkter fokuserede og håndterbare.
Hændelsestrigger og Payload
Når en statusændring opstår, f. eks.
når en kunde gennemfører en SCA-udfordring, genererer systemet en JSON-payload. Denne payload indeholder strukturerede data, herunder transaktions-ID, Merchant ID (MID), beløb og den specifikke hændelsestype.
Gatewayen forsøger derefter at levere disse data til det registrerede endpoint.
Sikkerhed og Signaturverifikation
For at forhindre uautoriseret dataindsprøjtning signeres payloadet typisk med en hemmelig nøgle. Forhandlerserveren rekonstruerer signaturen ved hjælp af den rå anmodningskrop og sammenligner den med headeren.
Denne verifikation sikrer, at dataene stammer fra den betroede kilde og ikke blev manipuleret under transit.
Bekræft og Behandl
Forhandlerserveren skal straks returnere en 200 OK-statuskode for at bekræfte modtagelsen. Intern logik udføres derefter, såsom opdatering af en databasepost eller udløsning af en automatisk e-mail.
Hvis serveren er offline eller returnerer en fejl, følger leveringssystemet en programmeret genforsøgsplan for at sikre datakonsistens.
Hvorfor det betyder noget
Operationel Effektivitet og Automatisering
At stole på manuelle statuskontroller eller periodisk API-polling introducerer latenstid, der kan forringe brugeroplevelsen og forsinke opfyldelsen. Webhooks automatiserer overgangen mellem betalingsautorisation og servicelevering.
Ved at modtage øjeblikkelig meddelelse om vellykkede indfangninger eller afregninger kan virksomheder automatisere forsendelsesworkflow, licensgenerering eller kontooprettelse, hvilket reducerer behovet for manuel intervention og minimerer risikoen for menneskelige fejl i transaktionsstyring.
Risiko- og Tvistbegrænsning
Notifikationer om genoprettelsesanmodninger eller chargebacks giver forhandlere mulighed for at reagere inden for ordningens fastsatte tidsfrister. Øjeblikkelige advarsler vedrørende bløde afvisninger eller SCA-fejl muliggør proaktiv kundeengagement.
Ved at reagere på disse hændelser, når de sker, kan forhandlere forbedre deres succesrater for repræsentation og reducere de driftsomkostninger, der er forbundet med uadresserede betalingsfejl eller tvister, der ellers ville være gået ubemærket hen indtil en periodisk manuel revision.
Anvendelser
Abonnement og SaaS Livscyklus
Når en tilbagevendende betaling mislykkes, eller et kort udløber, udløser en webhook en automatiseret dunning-sekvens eller suspenderer brugerens adgang, hvilket opretholder nøjagtige faktureringscyklusser uden manuelt tilsyn.
E-handel Ordreopfyldelse
En onlineforhandler bruger webhooks til at frigive varer til forsendelse først efter at have modtaget en 'capture. succeeded'-hændelse, hvilket forhindrer afsendelse af varer, for hvilke betaling ikke er fuldt autoriseret.
Markedsplads Udbetalingskoordinering
Platforme, der modtager midler, kan udløse udbetalinger til underforhandlere først efter at den oprindelige kundetransaktion har opnået en afregnet status, hvilket sikrer likviditet og reducerer risikoen for udbetalingsomstødninger.
Alternativ Betalingsmetode Afslutning
For metoder som bankoverførsler eller lokale ordninger, der ikke giver øjeblikkelig bekræftelse, underretter webhooks systemet timer eller dage senere, når midlerne er bekræftet.
I tal
Typisk brancheforsinkelse mellem en hændelse, der registreres i erhvervelsesplatformen, og webhook'en, der sendes til forhandlerens endpoint.
Standard pålidelighedsbenchmark for webhook-tjenester, når der inkluderes automatisk genforsøgslogik og redundant leveringsinfrastruktur.
Brancheobservation af forbedring i opfyldelseshastighed ved overgang fra periodisk batchbehandling til hændelsesdrevne webhook-arkitekturer.
Relaterede termer
Talk to our team about a live rollout on your acquiring stack.
Hvad du får med Webhooks
- Asynkron levering af ændringer i transaktionsstatus for forbedret systemydelse.
- Understøttelse af flere hændelsestyper, herunder autorisation, indfangning, refusion og tvist.
- HMAC-SHA256 signatur-headers for robust verifikation af indgående dataintegritet.
- Automatisk genforsøgslogik efter eksponentielle backoff-skemaer for mislykkede leveringsforsøg.
- Payload-versionering for at sikre kompatibilitet, efterhånden som datastrukturer udvikler sig over tid.
- IP-whitelisting-funktioner til at begrænse indgående trafik til kendte gateway-kilder.
- Inkludering af idempotensnøgle for at forhindre dobbeltbehandling af den samme betalingshændelse.
- Detaljerede hændelseslogfiler til fejlfinding og revision af webhook-leveringsydelse inden for dashboardet.
- Granulær hændelsesudvælgelse for at minimere båndbreddeforbrug og server-side behandlingskrav.
- Testtilstandsfunktionalitet til validering af endpoint-adfærd med simulerede betalingsscenarier.
A short scoping call, then a written plan for your MIDs.
Spørgsmål om Webhooks
Hvordan skal vores server håndtere duplikerede webhook-notifikationer?
Det er standardpraksis for betalingsgateways at anvende en genforsøgsmekanisme, hvis et endpoint ikke returnerer en 200 OK-respons inden for en bestemt tidsramme. Derfor kan din server modtage den samme hændelse flere gange.
For at opretholde dataintegritet bør du implementere idempotenslogik. Dette involverer typisk sporing af det unikke hændelses-ID, der er angivet i payloadet, og kontrol af, om det allerede er blevet behandlet, før forretningslogik udføres.
Hvis ID'et findes i din database, skal din server ignorere hændelsen, men stadig returnere en 200 OK for at stoppe yderligere genforsøg.
Hvad er forskellen mellem at polle en API og bruge webhooks?
Polling kræver, at din server initierer hyppige anmodninger til gatewayen for at kontrollere statusopdateringer, hvilket er ineffektivt og kan føre til rate-limiting-problemer eller forsinket information. Webhooks vender denne strøm, hvor gatewayen initierer en anmodning til din server, kun når en hændelse opstår.
Denne 'push'-model er mere effektiv, reducerer serverbelastningen og sikrer, at statusser opdateres i næsten realtid på tværs af din infrastruktur, hvilket er særligt vigtigt for tidssensitive handlinger som levering af digitalt indhold eller forebyggelse af svindel.
Hvorfor er signaturverifikation nødvendig for hver webhook-anmodning?
Da webhook-endpoints er offentlige URL'er, er de teoretisk tilgængelige for enhver enhed på internettet. Uden verifikation kunne en angriber sende en forfalsket JSON-payload til din server, der falsk indikerer, at en betaling af høj værdi var vellykket.
Ved at bruge en delt hemmelighed til at verificere HMAC-signaturen, der er angivet i anmodningsheaderen, kan dit system matematisk bevise, at meddelelsen blev sendt af din PSP, og at indholdet ikke er blevet ændret, hvilket sikrer sikkerheden i din ordreopfyldelsesproces.
Hvordan håndterer webhooks 3-D Secure og SCA-krav?
Under et 3-DS-flow går transaktionen ofte i en afventende tilstand, mens brugeren omdirigeres til deres udsteder for godkendelse. Det endelige resultat af denne godkendelse er muligvis ikke kendt med det samme.
Webhooks bruges til at underrette dit system, når 3-DS-udfordringen er afsluttet, og transaktionen efterfølgende er godkendt eller afvist. Dette forhindrer din checkout i at hænge og giver din backend mulighed for at reagere på den endelige godkendelsesstatus, når kunden vender tilbage fra bankens omdirigeringsside.
Kan webhooks bruges til at administrere chargeback- og tvisttidslinjer?
Ja, webhooks er et primært værktøj til at administrere tvistlivscyklussen. Når en kortholder initierer en Retrieval Request eller en formel Chargeback med deres udsteder, modtager gatewayen denne notifikation via kortordningerne.
En webhook sendes derefter til dit system, der specificerer årsagskoden, beløbet og fristen for svar.
Ved at bruge disse realtidsdata kan du automatisere suspenderingen af den relevante konto og underrette dit risikoteam om at starte repræsentationsprocessen med det samme, hvilket øger sandsynligheden for en vellykket tvistomstødelse.
Hvad sker der, hvis vores server er nede under en kritisk webhook-hændelse?
Pålidelige webhook-systemer fungerer med en genforsøgspolitik. Hvis dit endpoint returnerer en 4xx- eller 5xx-fejl, eller undlader at svare inden for få sekunder, vil gatewayen sætte meddelelsen i kø til genlevering.
Disse genforsøg følger normalt et eksponentielt backoff-mønster, der forsøger levering flere gange over minutter eller timer.
For at sikre langsigtet konsistens bør du også have en fallback-mekanisme, såsom et dagligt afstemningsscript, der kalder API'en for at finde eventuelle missede statusændringer, hvilket giver et sikkerhedsnet for længerevarende nedbrud.
Relaterede funktioner.
Klar til fart?
Fortæl os om din virksomhed. Vi matcher dig med de rigtige ’acquiring’-partnere og den rigtige rute, typisk inden for en uge.