Webhooks
Event-driven payment architectures require reliable asynchronous notifications to update order management systems when transaction states change. Cardflo delivers payment webhooks with cryptographic signatures and exponential backoff schedules to ensure backend servers process lifecycle events securely.
- Category
- Developer
- Capabilities
- 10
- Available on
- All plans
Webhooks provide real-time, event-driven notifications for critical payment lifecycle updates. Cardflo's webhooks enable your systems to react instantly to payment statuses, disputes, and other key events.
Automate workflows and maintain synchronisation between your platform and Cardflo without constant polling.
Timely webhook notifications deliver real-time updates on transaction statuses and MID activity across our extensive acquirer network. This instant data flow enables rapid automation of critical business processes and immediate responses to events.
Webhooks overview
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 3D 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.
How webhooks works
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 unauthorised 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.
Why webhooks matters
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.
Webhooks use cases
Capture event ledger updates
Finance ledgers consuming capture, void and refund events can misstate transaction state when notifications arrive late, duplicated or out of order. Cardflo supplies structured JSON payloads with event and transaction identifiers, allowing handlers to enforce idempotency, record lifecycle transitions and reject invalid state changes.
Asynchronous wallet top-up updates
Public listener endpoints receiving payment webhooks risk accepting forged payloads or replayed events if request authenticity and freshness are not checked. Cardflo supports cryptographic signature verification, while backend teams validate signatures against the raw request body, enforce timestamp tolerances and restrict processing to recognised event types.
Failed delivery retry handling
Temporary listener outages, deployment restarts and upstream timeouts can prevent transaction status events from reaching an event-driven application on the first attempt. Cardflo retries failed webhook deliveries, while operators return appropriate HTTP status codes, process events idempotently and retain delivery logs for incident analysis.
Order fulfilment after capture
Order systems must not release warehouse pick instructions when an authorisation is later voided or capture remains incomplete. Cardflo sends asynchronous capture, decline, void and refund events, enabling fulfilment services to verify the signed JSON payload and advance orders only when the recorded lifecycle state permits dispatch.
Webhooks by the numbers
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.
Methodology: these figures are illustrative ranges drawn from published industry data and observed merchant cohorts, not guarantees. Actual results depend on your risk profile, card mix, geography and acquiring setup, and are confirmed only in your own pricing and approval terms.
Related terms
Talk to our team about a live rollout across our acquirer partners' rails.
What you get with Webhooks
- Asynchronous delivery of transaction status changes for improved system performance.
- Support for multiple event types including authorisation, capture, refund, and dispute.
- HMAC-SHA256 signature headers for robust verification of incoming data integrity.
- Automated retry logic following exponential backoff schedules for failed delivery attempts.
- Payload versioning to ensure compatibility as data structures evolve over time.
- IP whitelisting capabilities to restrict incoming traffic to known gateway sources.
- 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.
Questions about Webhooks
How should our server handle duplicate webhook notifications?
It is standard practice for payment gateways to employ a retry mechanism if an endpoint does not return a 200 OK response within a specific timeframe. Consequently, your server may receive the same event multiple times.
To maintain data integrity, you should implement idempotency logic. This typically involves tracking the unique event ID provided in the payload and checking if it has already been processed before executing any business logic.
If the ID exists in your database, your server should ignore the event but still return a 200 OK to stop further retries.
What is the difference between polling an API and using webhooks?
Polling requires your server to initiate frequent requests to the gateway to check for status updates, which is inefficient and can lead to rate-limiting issues or delayed information.
Webhooks reverse this flow, where the gateway initiates a request to your server only when an event occurs.
This 'push' model is more efficient, reducing server load and ensuring that statuses are updated in near real-time across your infrastructure, which is particularly important for time-sensitive actions like digital content delivery or fraud prevention.
Why is signature verification necessary for every webhook request?
Since webhook endpoints are public URLs, they are theoretically accessible by any entity on the internet. Without verification, an attacker could send a spoofed JSON payload to your server, falsely indicating that a high-value payment was successful.
By using a shared secret to verify the HMAC signature provided in the request header, your system can mathematically prove the message was sent by your PSP and that the content has not been altered, ensuring the security of your order fulfilment process.
How do webhooks handle 3D 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.
Related features.
Related guides.
See how Cardflo compares.
Ready to improve your payments setup?
Tell us about your business. We'll match you with the right acquiring partners and the right route, typically inside a week.