Webhook
I webhook forniscono notifiche in tempo reale, basate su eventi, per gli aggiornamenti critici del ciclo di vita dei pagamenti. I webhook di Cardflo consentono ai tuoi sistemi di reagire istantaneamente agli stati dei pagamenti, alle contestazioni e ad altri eventi chiave.
Automatizza i flussi di lavoro e mantieni la sincronizzazione tra la tua piattaforma e Cardflo senza polling costante.
- Categoria
- Sviluppatore
- Funzionalità
- 10
- Disponibile su
- Tutti i piani
La panoramica
Webhooks function as asynchronous HTTP callbacks that facilitate real-time communication between a payments gateway and a merchant server.
Unlike traditional polling methods where a server makes repetitive requests to check for status updates, webhooks push data to a pre-defined URL the moment a specific event occurs within the payment lifecycle.
This mechanism is critical for managing non-synchronous events such as 3-D Secure authentication results, asynchronous Alternative Payment Method (APM) completions, or the receipt of a chargeback.
Within the payments stack, webhooks act as the connective tissue between the acquirer or PSP and the merchant's internal order management system (OMS) or revenue management platform.
They ensure that subsequent logic, such as inventory locking or digital entitlement, remains accurate without introducing latency or unnecessary API overhead.
Proper implementation requires robust handling of HTTP status codes and idempotency to manage potential retries from the sending server, ensuring each event is processed once and only once.
Come funziona
Define Endpoint and Events
A merchant specifies a destination URL within their environment to receive POST requests. They select specific event triggers from the payment lifecycle, such as authorisation success, refund initiation, or dispute creation.
This ensures their system only processes relevant data packets, reducing unnecessary server load and keeping integration points focused and manageable.
Event Trigger and Payload
When a status change occurs, such as a customer completing an SCA challenge, the system generates a JSON payload. This payload contains structured data, including the transaction ID, Merchant ID (MID), amount, and the specific event type.
The gateway then attempts to deliver this data to the registered endpoint.
Security and Signature Verification
To prevent unauthorized data injection, the payload is typically signed with a secret key. The merchant server reconstructs the signature using the raw request body and compares it against the header.
This verification ensures the data originated from the trusted source and was not tampered with during transit.
Acknowledge and Process
The merchant server must return a 200 OK status code promptly to acknowledge receipt. Internal logic then executes, such as updating a database record or triggering an automated email.
If the server is offline or returns an error, the delivery system follows a programmed retry schedule to ensure data consistency.
Perché è importante
Operational Efficiency and Automation
Relying on manual status checks or periodic API polling introduces latency that can degrade the user experience and delay fulfilment. Webhooks automate the transition between payment authorisation and service delivery.
By receiving immediate notification of successful captures or settlement, businesses can automate shipping workflows, licence generation, or account provisioning, reducing the need for manual intervention and minimising the risk of human error in transaction management.
Risk and Dispute Mitigation
Notifications for retrieval requests or chargebacks allow merchants to respond within scheme-mandated timeframes. Immediate alerts regarding soft declines or SCA failures enable proactive customer engagement.
By reacting to these events as they happen, merchants can improve their representment success rates and reduce the operational costs associated with unaddressed payment failures or disputes that otherwise might have gone unnoticed until a periodic manual audit.
Casi d'uso
Subscription and SaaS Lifecycle
When a recurring payment fails or a card expires, a webhook triggers an automated dunning sequence or suspends the user's access, maintaining accurate billing cycles without manual oversight.
E-commerce Order Fulfilment
An online retailer uses webhooks to release goods for shipping only after receiving a 'capture. succeeded' event, preventing the despatch of items for which payment has not been fully authorised.
Marketplace Payout Coordination
Platforms receiving funds can trigger disbursements to sub-merchants only after the initial customer transaction achieves a settled status, ensuring liquidity and reducing the risk of payout reversals.
Alternative Payment Method Finalisation
For methods like bank transfers or local schemes that do not provide instant confirmation, webhooks notify the system hours or days later when funds are confirmed.
In cifre
Typical industry delay between an event being recorded in the acquiring platform and the webhook being dispatched to the merchant endpoint.
Standard reliability benchmark for webhook services when including automated retry logic and redundant delivery infrastructure.
Industry observation of improvement in fulfilment speed when transitioning from periodic batch processing to event-driven webhook architectures.
Termini correlati
Talk to our team about a live rollout on your acquiring stack.
Cosa ottieni con Webhook
- Notifiche in tempo reale per le modifiche dello stato delle transazioni.
- Automatizza l'evasione degli ordini in caso di pagamento andato a buon fine.
- Attiva la comunicazione con il cliente per pagamenti falliti o rimborsi.
- Sincronizza lo stato degli abbonamenti con i tuoi sistemi interni.
- Ricevi avvisi per chargeback e aggiornamenti sulle contestazioni.
- Consegna sicura dei webhook con verifica della firma.
- Idempotency key inclusion to prevent duplicate processing of the same payment event.
- Detailed event logs for debugging and auditing webhook delivery performance within the dashboard.
- Granular event selection to minimise bandwidth usage and server-side processing requirements.
- Test mode functionality for validating endpoint behaviour with simulated payment scenarios.
A short scoping call, then a written plan for your MIDs.
Domande su Webhook
Quali tipi di eventi coprono i webhook di Cardflo?
I webhook di Cardflo coprono una serie di eventi critici, inclusi pagamenti andati a buon fine, pagamenti falliti, rimborsi, chargeback, aggiornamenti sulle contestazioni e modifiche allo stato degli abbonamenti.
Ciò garantisce che il tuo sistema sia immediatamente informato di qualsiasi attività rilevante, consentendo un'azione tempestiva e la sincronizzazione del sistema.
Come si configurano e si proteggono i webhook?
I commercianti possono configurare gli endpoint dei webhook nella loro dashboard Cardflo o tramite API. La sicurezza è garantita da firme crittografiche incluse in ogni payload.
Il tuo sistema può verificare questa firma per confermare l'autenticità e l'integrità della notifica del webhook, prevenendo lo spoofing.
I webhook possono essere utilizzati per la riconciliazione?
Sì, i webhook sono uno strumento prezioso per la riconciliazione in tempo reale. Ricevendo notifiche immediate di pagamenti andati a buon fine, fallimenti e rimborsi, i tuoi sistemi di contabilità e gestione degli ordini possono aggiornare i record istantaneamente.
Ciò riduce lo sforzo manuale e migliora l'accuratezza nella tracciabilità finanziaria.
How do webhooks handle 3-D Secure and SCA requirements?
During a 3-DS flow, the transaction often moves into a pending state while the user is redirected to their issuer for authentication. The final result of this authentication may not be known immediately.
Webhooks are used to notify your system when the 3-DS challenge is completed and the transaction is subsequentlly authorised or declined.
This prevents your checkout from hanging and allows your backend to react to the final authorisation state once the customer returns from the bank's redirect page.
Can webhooks be used to manage chargeback and dispute timelines?
Yes, webhooks are a primary tool for managing the dispute lifecycle. When a cardholder initiates a Retrieval Request or a formal Chargeback with their issuer, the gateway receives this notification via the card schemes.
A webhook is then sent to your system specifying the reason code, amount, and deadline for response.
Using this real-time data, you can automate the suspension of the relevant account and notify your risk team to begin the representment process immediately, increasing the likelihood of a successful dispute reversal.
What happens if our server is down during a critical webhook event?
Reliable webhook systems operate with a retry policy. If your endpoint returns a 4xx or 5xx error, or fails to respond within a few seconds, the gateway will queue the message for re-delivery.
These retries usually follow an exponential backoff pattern, attempting delivery several times over minutes or hours.
To ensure long-term consistency, you should also have a fallback mechanism, such as a daily reconciliation script that calls the API to find any missed status changes, providing a safety net for extended outages.
Funzionalità correlate.
Pronto per la velocità?
Raccontaci della tua attività. Ti abbineremo ai giusti partner acquirenti e al percorso giusto, di solito entro una settimana.