Webhooks
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.
- Category
- Developer
- Capabilities
- 10
- Available on
- All plans
The 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 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.
How it 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 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.
Why it 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.
Use cases
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.
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.
Related terms
Talk to our team about a live rollout on your acquiring stack.
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 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.
Related features.
Ready for velocity?
Tell us about your business. We'll match you with the right acquiring partners and the right route, typically inside a week.