Reliable payment gateway integration depends on more than receiving a successful payment response. This checklist explains how to process payment webhooks and notifications so orders, refunds, disputes, subscriptions, and payouts remain accurate—even when events arrive more than once, out of order, or after a temporary delivery failure.
Overview
A webhook is a server-to-server notification sent by a payment provider when something changes. Depending on the gateway, events may represent an authorization, capture, refund, dispute, subscription update, payout, or delivery failure. Your application receives the event, verifies that it is genuine, records it, and performs the appropriate business action.
Webhooks should complement—not replace—direct API requests. A checkout request can return an immediate result for the customer interface, while the webhook provides an asynchronous record that your backend can use to confirm the provider’s state. This distinction matters when a payment requires additional authentication, settles later, is reversed, or changes after the customer leaves checkout.
The safest design treats every event as an input to a controlled state machine. Your system should not simply mark an order as paid because it received a notification with a familiar status. It should validate the event, check the related object, apply an allowed state transition, and retain enough data to explain what happened during support reviews or reconciliation.
For related implementation work, compare this guide with the Payment Gateway API Integration Checklist, particularly when planning refunds, retries, and go-live testing.
What to track
1. Event identity and delivery metadata
Store the provider’s event ID, event type, creation time, delivery attempt information when available, and the time your system received the message. The event ID is the primary key for idempotency: if the same notification arrives again, your application should recognize it rather than create a second order update, refund, email, or ledger entry.
Also retain the payment, order, customer, invoice, refund, dispute, or payout identifier included in the event. These relationships make it possible to trace a business record back to the provider dashboard and to investigate a missing or unexpected transition.
2. Signature verification and authentication
Verify each incoming notification using the authentication method documented by the provider. Common patterns include a signed header, a timestamped signature, or a secret associated with a webhook endpoint. Verify the signature against the raw request body before parsing or transforming the payload if the provider requires the original bytes.
Keep webhook secrets out of source control, use separate credentials for test and production environments, and plan a controlled rotation process. Do not treat an event as trusted merely because it reached an obscure URL. Reject requests that fail verification, and log the reason without exposing secrets or complete payment data.
Security controls should fit within your wider secure payment processing and PCI compliance program. The PCI Compliance for Small Businesses checklist can help teams place gateway integration tasks in the correct compliance workflow.
3. Business actions by event
Map each provider event to one or more deliberate actions. The exact event names differ by gateway, so maintain a translation layer between provider-specific names and your internal states.
| Event category | Business action | Control to verify |
|---|---|---|
| Payment authorized | Record authorization and keep the order in an authorized or pending state. | Do not treat authorization as settlement unless the payment model says it is immediate. |
| Payment captured or succeeded | Mark the order or invoice as paid, release fulfillment, and record the provider transaction ID. | Confirm amount, currency, customer reference, and order reference match. |
| Payment failed or canceled | Keep the order unpaid, show an appropriate next step, and avoid fulfillment. | Store a safe failure reason for support without exposing sensitive details. |
| Refund created or completed | Record the refund against the original payment and update the order or subscription balance. | Support partial refunds and prevent the same refund from being counted twice. |
| Dispute opened | Flag the transaction, pause relevant workflows, and create an evidence task with a deadline field if supplied. | Separate a dispute from a normal refund and track later dispute outcomes. |
| Subscription or invoice changed | Update access, billing status, plan details, or retry workflows according to your product rules. | Use the provider’s invoice or subscription ID as well as your internal account ID. |
| Payout initiated, paid, or failed | Update cash-flow reporting and reconciliation records. | Reconcile payout totals against included transactions, fees, reserves, and adjustments. |
4. Idempotency and ordering
Idempotency means processing the same event repeatedly produces the same business result as processing it once. Enforce this with a durable event table or equivalent record protected by a unique constraint on the provider event ID. Mark an event as received before beginning side effects only if your worker design can safely resume incomplete work; otherwise use an explicit status such as received, processing, applied, and failed.
Do not assume events arrive in chronological order. A refund notification may arrive before a later payment update, or a retry may appear after a newer event. When order matters, compare the provider object’s current version, update time, or status rather than relying solely on delivery order. If the payload is insufficient, retrieve the current object through the provider API before applying the transition.
5. Delivery and reconciliation metrics
Track accepted events, rejected signatures, duplicate events, processing failures, processing duration, retry count, and events that remain unprocessed. Monitor these by event type and environment. A healthy delivery rate alone does not prove that orders are accurate; compare webhook-derived records with provider dashboard data and your own order, refund, and payout tables.
Cadence and checkpoints
Use a repeatable review schedule rather than waiting for a customer to report a missing payment. A monthly review is appropriate for active integrations; a quarterly review may suit lower-volume systems, provided critical alerts are handled immediately.
- Every deployment: Run test-mode scenarios for success, failure, duplicate delivery, invalid signature, delayed delivery, refund, and any authentication step used in checkout.
- Monthly: Review failed deliveries, unprocessed events, duplicate rates, processing latency, and the dead-letter or retry queue. Sample records from orders, refunds, disputes, and payouts.
- Quarterly: Compare your internal event map with the provider’s current API and webhook documentation. Check API versions, endpoint authentication, signing requirements, event names, retry behavior, SDK versions, and payload fields.
- Before a migration: Confirm whether the old and new endpoints can receive overlapping traffic, how events are deduplicated, and how historical records will be reconciled. Test rollback without creating duplicate side effects.
- After an incident: Preserve logs, identify the first failed event, replay safely in a non-production environment where possible, and document the corrective action.
Keep a compact integration register containing the provider, account and environment identifiers, endpoint URLs, API version, event types in use, secret rotation date, owner, alert destination, and last successful test date. This turns a complex payment API integration into an auditable operational process.
How to interpret changes
A rise in duplicate events does not necessarily indicate a gateway problem; it may reflect slow acknowledgments, worker timeouts, or a deployment that stopped returning a successful response quickly. Investigate delivery logs and response times before changing business logic. Your endpoint should acknowledge a valid event promptly and perform heavier work asynchronously when the provider’s model permits it.
An increase in signature failures may indicate a rotated secret, a test and production configuration mix-up, altered request-body handling, clock problems in timestamp validation, or an untrusted request. Treat it as a security and availability issue. Do not disable verification to restore delivery without an approved temporary control.
Missing events require a different investigation. Compare the provider dashboard, your ingress logs, the webhook event table, and the business record. If the provider supports event retrieval or replay, use that capability cautiously and preserve the original event ID. If no event exists, query the provider object directly and record why the reconciliation job changed the internal state.
Differences between your totals and payout reports can result from timing, refunds, disputes, fees, reserves, currency conversion, or transactions included in a different payout window. For cross-border activity, review the settlement currency and conversion assumptions described in the Multi-Currency Payment Gateway Guide. For recurring billing, compare invoice and subscription states using the Subscription Billing Setup Guide as a related reference.
Troubleshooting template
When an event is missing, duplicated, or incorrectly applied, record:
- Business record: order, invoice, refund, dispute, or payout ID.
- Provider references: event ID, object ID, account, environment, and event type.
- Timeline: provider creation time, delivery attempts, receipt time, processing time, and any manual action.
- Verification: signature result, endpoint response code, and whether the raw payload was retained safely.
- Processing result: idempotency lookup, state transition attempted, side effects completed, and error message.
- Comparison: provider dashboard state versus internal state and ledger or payout records.
- Resolution: replay, API recheck, manual correction, code change, configuration change, or escalation.
When to revisit
Revisit this payment webhooks guide on your monthly or quarterly operations cadence, and immediately when the provider changes its API version, event names, authentication method, payload schema, SDK behavior, retry policy, or dashboard workflow. Review it before launching a new payment method, adding subscriptions, enabling cross-border settlement, changing fulfillment rules, or migrating gateways.
Make the next review practical: select a small sample of successful payments, failed payments, refunds, disputes, and payouts; trace each from provider event to internal record; confirm duplicate protection; and run one controlled replay. Then update your event map, integration register, test cases, and runbook. If a change affects authentication or checkout, also review the relevant 3D Secure and Strong Customer Authentication guide.
The goal is not to eliminate every delivery delay. It is to ensure that delays, duplicates, and changes are visible, recoverable, and unable to create incorrect financial or fulfillment outcomes.