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
- 6
- Available on
- All plans
Event-driven applications must maintain accurate transaction states across disparate databases when network latency interrupts standard communication flows. Backend systems require reliable notifications for authorisations, captures, and refunds without continuously querying external servers. Engineers need structured payloads that clearly identify the specific event type and the associated merchant identifier.
Cardflo transmits structured JSON payloads directly to designated listener URLs whenever an asynchronous event occurs within the acquirer partner network. The orchestration engine signs every outbound request cryptographically, allowing system reliability engineers to validate data origin. Automated retry mechanisms follow an exponential backoff schedule if the receiving server returns errors.
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
Building resilient transaction pipelines demands an architecture that pushes state changes directly to a designated server through payment webhooks. Rather than requesting synchronous data, as detailed on the developer-friendly API page, backend engineers register specific listener URLs to receive asynchronous payload deliveries.
The gateway orchestration layer transmits structured JSON data detailing captures, refunds, chargebacks, and 3D Secure authentication outcomes. Development teams configure these notification routes to automate database updates, trigger order fulfilment processes, and reconcile ledger entries programmatically.
Every outbound transmission includes a cryptographic hash in the header, ensuring that the receiving application can authenticate the origin and integrity of the data before processing it. The infrastructure supports configurable retry policies, managing temporary network interruptions or server downtime by attempting redelivery across subsequent intervals.
How webhooks works
Endpoint configuration and subscription
System reliability engineers specify a receiving HTTPS URL within the orchestration platform and select which payment status notifications to monitor. The system generates an exclusive secret token associated with that endpoint. The gateway then binds these configuration parameters, ensuring only the selected event types trigger an outbound transmission to the registered server address, while ignoring unrelated transaction updates.
Payload generation and transmission
When a transaction progresses through the acquirer partner network, the orchestration engine creates a structured JSON document. This file contains the transaction identifier, the specific event type, and the relevant financial amounts. The gateway calculates an HMAC signature using the endpoint secret and transmits the entire package as an HTTP POST request to the merchant infrastructure.
Signature validation and processing
The receiving server extracts the cryptographic signature from the incoming request header. Backend applications compute a matching hash using the raw payload body and the stored endpoint secret. If the values align, the application acknowledges the delivery with a standard HTTP success code and routes the updated transaction state into the core order management database.
Why webhooks matters
Minimised server resource consumption
Relying on asynchronous payment events reduces unnecessary outbound network requests and database queries. Infrastructure engineers can allocate computational resources toward user-facing applications rather than maintaining constant query loops. This architecture lowers cloud hosting costs and prevents rate-limiting issues when processing high volumes of concurrent transactions during peak trading periods.
Accurate order state management
Delayed or missing transaction updates lead to unfulfilled orders, delayed shipping, and elevated customer support tickets. Notification listeners ensure that inventory management systems reflect the true financial status immediately after an acquirer partner confirms a capture or refund. Finance teams benefit from exact ledger reconciliation without manual intervention or data discrepancies.
Regulatory notes for webhooks
Data privacy and payload security
Transmitting transaction data across open networks leaves no slack against data protection regulations like GDPR and PCI DSS. Notification payloads must travel exclusively over TLS-encrypted connections to prevent interception by unauthorised third parties during transit.
Cardflo enforces HTTPS URLs for all registered listener endpoints, rejecting any unencrypted destinations.
Furthermore, structured notifications exclude sensitive cardholder data, such as full primary account numbers or security codes. The gateway transmits tokenised identifiers and masked references, ensuring that the receiving server does not inadvertently bring its hosting environment into the highest tiers of PCI DSS compliance scope.
PSD2 and asynchronous strong customer authentication
Under Payment Services Directive 2, Strong Customer Authentication introduces asynchronous flows into the standard checkout process. When a transaction requires an out-of-band authentication step, such as a biometric check in a banking application, the initial request cannot return an immediate definitive success or failure status.
Event listeners are essential for capturing the final outcome of these mandated security challenges. Once the issuing bank confirms the authentication result through the acquirer partner network, the orchestration layer fires an asynchronous event.
This notification informs the merchant system that the security requirement is satisfied and the capture can proceed.
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
- Delivery of structured JSON payloads for distinct transaction lifecycle changes and asynchronous payment events.
- Cryptographic webhook signature verification using HMAC-SHA256 headers to authenticate the gateway orchestration origin securely.
- Configurable listener endpoint URLs that receive targeted event types based on merchant routing preferences.
- Automated retry schedules implementing exponential backoff to handle temporary server downtime and network timeouts.
- Granular event subscriptions allowing development teams to filter specific notifications like chargebacks or refunds.
- Idempotency keys included within the payment gateway webhook payload to prevent duplicate database updates.
A short scoping call, then a written plan for your MIDs.
Questions about Webhooks
How is a payment gateway webhook payload verified securely?
Applications must extract the custom signature header from the incoming HTTP POST request. Backend developers then use the raw, unmodified JSON request body and the shared endpoint secret to compute an HMAC-SHA256 hash.
Comparing this locally generated hash against the transmitted header confirms both the origin of the request and that the data remained unaltered during transit. Failing this verification step indicates a potentially malicious payload, which the receiving server should discard immediately with a standard error response.
What happens if a listener endpoint returns an error?
The gateway orchestration layer expects a standard HTTP success code within a defined timeout window. If the receiving server returns a server error, a client error, or times out completely, the system queues the event for redelivery.
The automated retry mechanism employs an exponential backoff schedule, increasing the delay between each subsequent attempt. This approach protects merchant infrastructure during temporary outages while ensuring that critical asynchronous payment events eventually reach the target database.
How are out-of-order event deliveries handled?
Network latency can occasionally cause notifications to arrive out of chronological sequence. Every transmission includes a precise timestamp and a unique event identifier.
Backend engineers must design their receiving logic to check these timestamps against the current state stored in the local database.
If an application receives an authorisation notification after it has already processed a capture event for the same transaction, the logic should ignore the older status to preserve database integrity.
Can development teams filter the event notifications by type?
Yes, the endpoint configuration allows precise subscription management for different notification categories.
A merchant might configure one URL dedicated exclusively to dispute and chargeback alerts for the risk team, while a separate server address handles standard authorisation and capture notifications for the primary order management system.
Granular subscriptions reduce unnecessary network traffic and ensure that individual microservices only parse the payload data relevant to their specific operational domain.
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.