Webhooks
Webhooks bieden realtime, gebeurtenisgestuurde meldingen voor kritieke updates van de betalingslevenscyclus. De webhooks van Cardflo stellen uw systemen in staat direct te reageren op betalingsstatussen, geschillen en andere belangrijke gebeurtenissen.
Automatiseer workflows en handhaaf synchronisatie tussen uw platform en Cardflo zonder constant te pollen.
- Categorie
- Ontwikkelaar
- Mogelijkheden
- 10
- Beschikbaar op
- Alle abonnementen
Het overzicht
Webhooks functioneren als asynchrone HTTP-callbacks die realtime communicatie tussen een betalingsgateway en een merchantserver mogelijk maken.
In tegenstelling tot traditionele polling-methoden waarbij een server herhaaldelijk verzoeken indient om te controleren op statusupdates, pushen webhooks gegevens naar een vooraf gedefinieerde URL op het moment dat een specifieke gebeurtenis plaatsvindt binnen de betalingslevenscyclus.
Dit mechanisme is cruciaal voor het beheren van niet-synchrone gebeurtenissen zoals 3-D Secure authenticatieresultaten, asynchrone Alternative Payment Method (APM) voltooiingen, of de ontvangst van een chargeback.
Binnen de betalingsstack fungeren webhooks als het verbindende weefsel tussen de acquirer of PSP en het interne orderbeheersysteem (OMS) of omzetbeheerplatform van de merchant. Ze zorgen ervoor dat de daaropvolgende logica, zoals voorraadvergrendeling of digitale rechten, nauwkeurig blijft zonder latentie of onnodige API-overhead te introduceren.
Een juiste implementatie vereist een robuuste afhandeling van HTTP-statuscodes en idempotentie om potentiële herhalingen van de verzendende server te beheren, zodat elke gebeurtenis één keer en slechts één keer wordt verwerkt.
Hoe het werkt
Definieer Endpoint en Gebeurtenissen
Een merchant specificeert een bestemmings-URL binnen hun omgeving om POST-verzoeken te ontvangen. Ze selecteren specifieke gebeurtenistriggers uit de betalingslevenscyclus, zoals autorisatiesucces, terugbetalingsinitiatie of geschilcreatie.
Dit zorgt ervoor dat hun systeem alleen relevante datapakketten verwerkt, waardoor onnodige serverbelasting wordt verminderd en integratiepunten gericht en beheersbaar blijven.
Gebeurtenistrigger en Payload
Wanneer een statuswijziging optreedt, zoals een klant die een SCA-uitdaging voltooit, genereert het systeem een JSON-payload. Deze payload bevat gestructureerde gegevens, waaronder de transactie-ID, Merchant ID (MID), het bedrag en het specifieke gebeurtenistype.
De gateway probeert vervolgens deze gegevens naar het geregistreerde endpoint te leveren.
Beveiliging en Handtekeningverificatie
Om ongeoorloofde gegevensinjectie te voorkomen, wordt de payload doorgaans ondertekend met een geheime sleutel. De merchantserver reconstrueert de handtekening met behulp van de onbewerkte verzoekbody en vergelijkt deze met de header.
Deze verificatie zorgt ervoor dat de gegevens afkomstig zijn van de vertrouwde bron en niet zijn gemanipuleerd tijdens het transport.
Bevestigen en Verwerken
De merchantserver moet onmiddellijk een 200 OK-statuscode retourneren om de ontvangst te bevestigen. Interne logica wordt vervolgens uitgevoerd, zoals het bijwerken van een databaserecord of het activeren van een geautomatiseerde e-mail.
Als de server offline is of een fout retourneert, volgt het leveringssysteem een geprogrammeerd herhalingsschema om gegevensconsistentie te garanderen.
Waarom het telt
Operationele Efficiëntie en Automatisering
Het vertrouwen op handmatige statuscontroles of periodieke API-polling introduceert latentie die de gebruikerservaring kan verslechteren en de afhandeling kan vertragen. Webhooks automatiseren de overgang tussen betalingsautorisatie en servicelevering.
Door onmiddellijke meldingen van succesvolle vastleggingen of afwikkelingen te ontvangen, kunnen bedrijven verzendworkflows, licentiegeneratie of accountprovisioning automatiseren, waardoor de noodzaak van handmatige tussenkomst wordt verminderd en het risico op menselijke fouten bij transactiebeheer wordt geminimaliseerd.
Risico- en Geschillenbeperking
Meldingen voor retrieval requests of chargebacks stellen merchants in staat te reageren binnen de door het schema voorgeschreven termijnen. Onmiddellijke waarschuwingen over soft declines of SCA-fouten maken proactieve klantbetrokkenheid mogelijk.
Door op deze gebeurtenissen te reageren zodra ze plaatsvinden, kunnen merchants hun succespercentages voor representatie verbeteren en de operationele kosten verminderen die gepaard gaan met onopgeloste betalingsfouten of geschillen die anders onopgemerkt zouden zijn gebleven tot een periodieke handmatige audit.
Toepassingen
Abonnement- en SaaS-levenscyclus
Wanneer een terugkerende betaling mislukt of een kaart verloopt, activeert een webhook een geautomatiseerde aanmaningsreeks of schort de toegang van de gebruiker op, waardoor nauwkeurige factureringscycli worden gehandhaafd zonder handmatig toezicht.
E-commerce Orderafhandeling
Een online retailer gebruikt webhooks om goederen vrij te geven voor verzending pas na ontvangst van een 'capture. succeeded'-gebeurtenis, waardoor het verzenden van artikelen waarvoor de betaling niet volledig is geautoriseerd, wordt voorkomen.
Coördinatie van Marketplace Uitbetalingen
Platforms die fondsen ontvangen, kunnen uitbetalingen aan sub-merchants activeren pas nadat de initiële klanttransactie een afgewikkelde status heeft bereikt, waardoor liquiditeit wordt gewaarborgd en het risico op uitbetalingsomkeringen wordt verminderd.
Finalisatie van Alternatieve Betaalmethoden
Voor methoden zoals bankoverschrijvingen of lokale schema's die geen onmiddellijke bevestiging bieden, stellen webhooks het systeem uren of dagen later op de hoogte wanneer fondsen zijn bevestigd.
In cijfers
Typische vertraging in de branche tussen het vastleggen van een gebeurtenis in het acquiringplatform en het verzenden van de webhook naar het merchant-endpoint.
Standaard betrouwbaarheidsbenchmark voor webhookdiensten bij inclusie van geautomatiseerde herhalingslogica en redundante leveringsinfrastructuur.
Industriële observatie van verbetering in afhandelingssnelheid bij de overgang van periodieke batchverwerking naar gebeurtenisgestuurde webhookarchitecturen.
Verwante termen
Talk to our team about a live rollout on your acquiring stack.
Wat u krijgt met Webhooks
- Asynchrone levering van wijzigingen in de transactiestatus voor verbeterde systeemprestaties.
- Ondersteuning voor meerdere gebeurtenistypen, waaronder autorisatie, vastlegging, terugbetaling en geschil.
- HMAC-SHA256 handtekeningheaders voor robuuste verificatie van de integriteit van inkomende gegevens.
- Geautomatiseerde herhalingslogica volgens exponentiële backoff-schema's voor mislukte leveringspogingen.
- Payload-versiebeheer om compatibiliteit te garanderen naarmate datastructuren in de loop van de tijd evolueren.
- IP-whitelisting-mogelijkheden om inkomend verkeer te beperken tot bekende gatewaybronnen.
- Inclusie van idempotentiesleutel om dubbele verwerking van dezelfde betalingsgebeurtenis te voorkomen.
- Gedetailleerde gebeurtenislogboeken voor het debuggen en controleren van de prestaties van webhooklevering binnen het dashboard.
- Granulaire gebeurtenisselectie om bandbreedtegebruik en server-side verwerkingsvereisten te minimaliseren.
- Testmodusfunctionaliteit voor het valideren van endpointgedrag met gesimuleerde betalingsscenario's.
A short scoping call, then a written plan for your MIDs.
Vragen over Webhooks
Hoe moet onze server omgaan met dubbele webhookmeldingen?
Het is standaardpraktijk voor betalingsgateways om een herhalingsmechanisme te gebruiken als een endpoint geen 200 OK-antwoord retourneert binnen een specifieke termijn. Bijgevolg kan uw server dezelfde gebeurtenis meerdere keren ontvangen.
Om de gegevensintegriteit te handhaven, moet u idempotente logica implementeren. Dit omvat doorgaans het bijhouden van de unieke gebeurtenis-ID die in de payload wordt geleverd en controleren of deze al is verwerkt voordat enige bedrijfslogica wordt uitgevoerd.
Als de ID in uw database bestaat, moet uw server de gebeurtenis negeren, maar nog steeds een 200 OK retourneren om verdere herhalingen te stoppen.
Wat is het verschil tussen het pollen van een API en het gebruik van webhooks?
Pollen vereist dat uw server frequent verzoeken initieert naar de gateway om te controleren op statusupdates, wat inefficiënt is en kan leiden tot rate-limiting problemen of vertraagde informatie.
Webhooks keren deze stroom om, waarbij de gateway een verzoek naar uw server initieert alleen wanneer een gebeurtenis plaatsvindt.
Dit 'push'-model is efficiënter, vermindert de serverbelasting en zorgt ervoor dat statussen in bijna realtime worden bijgewerkt in uw infrastructuur, wat vooral belangrijk is voor tijdgevoelige acties zoals digitale inhoudslevering of fraudepreventie.
Waarom is handtekeningverificatie noodzakelijk voor elk webhookverzoek?
Aangezien webhook-endpoints openbare URL's zijn, zijn ze theoretisch toegankelijk voor elke entiteit op het internet. Zonder verificatie zou een aanvaller een vervalste JSON-payload naar uw server kunnen sturen, ten onrechte aangevend dat een waardevolle betaling succesvol was.
Door een gedeeld geheim te gebruiken om de HMAC-handtekening in de verzoekheader te verifiëren, kan uw systeem wiskundig bewijzen dat het bericht door uw PSP is verzonden en dat de inhoud niet is gewijzigd, waardoor de veiligheid van uw orderafhandelingsproces wordt gewaarborgd.
Hoe gaan webhooks om met 3-D Secure en SCA-vereisten?
Tijdens een 3-DS-stroom komt de transactie vaak in een wachtende status terecht terwijl de gebruiker wordt omgeleid naar hun uitgever voor authenticatie. Het uiteindelijke resultaat van deze authenticatie is mogelijk niet onmiddellijk bekend.
Webhooks worden gebruikt om uw systeem op de hoogte te stellen wanneer de 3-DS-uitdaging is voltooid en de transactie vervolgens wordt geautoriseerd of geweigerd.
Dit voorkomt dat uw checkout blijft hangen en stelt uw backend in staat te reageren op de uiteindelijke autorisatiestatus zodra de klant terugkeert van de omleidingspagina van de bank.
Kunnen webhooks worden gebruikt om chargeback- en geschillenperiodes te beheren?
Ja, webhooks zijn een primair hulpmiddel voor het beheren van de geschillenlevenscyclus. Wanneer een kaarthouder een Retrieval Request of een formele Chargeback initieert bij hun uitgever, ontvangt de gateway deze melding via de kaartschema's.
Een webhook wordt vervolgens naar uw systeem gestuurd met de redencode, het bedrag en de deadline voor reactie.
Met behulp van deze realtime gegevens kunt u de opschorting van de relevante rekening automatiseren en uw risicoteam op de hoogte stellen om onmiddellijk het representatieproces te starten, waardoor de kans op een succesvolle geschillenomkering toeneemt.
Wat gebeurt er als onze server uitvalt tijdens een kritieke webhookgebeurtenis?
Betrouwbare webhooksystemen werken met een herhalingsbeleid. Als uw endpoint een 4xx- of 5xx-fout retourneert, of niet binnen enkele seconden reageert, zal de gateway het bericht in de wachtrij plaatsen voor herlevering.
Deze herhalingen volgen meestal een exponentieel backoff-patroon, waarbij de levering meerdere keren over minuten of uren wordt geprobeerd.
Om langdurige consistentie te garanderen, moet u ook een fallback-mechanisme hebben, zoals een dagelijks reconciliatiescript dat de API aanroept om gemiste statuswijzigingen te vinden, wat een vangnet biedt voor langdurige storingen.
Gerelateerde functies.
Klaar voor snelheid?
Vertel ons over uw bedrijf. Wij matchen u met de juiste acquiring partners en de juiste route, doorgaans binnen een week.