Most payment bugs that reach production are not really payment bugs. They are missed events. A charge succeeds but the order never updates, a refund clears but support never hears about it, funds settle but finance is still reconciling by hand. In almost every case, the gateway knew what happened — the integration just was not listening.

Payment gateway webhooks are how you listen. Instead of repeatedly asking “has anything changed?”, your application receives a signed message the moment something does. Get the right events wired up before launch and most of those silent failures simply never occur.

This guide walks through the webhook events worth tracking, why each one matters, and how to handle them reliably before you go live.

What Are Payment Gateway Webhooks?

A webhook is an HTTP callback. When a defined event happens inside the payment gateway — a payment is authorised, a charge fails, funds settle — the gateway sends a POST request to a URL you control, carrying a small JSON payload that describes the event.

A typical payload is generic in shape (field names vary by provider):

{
  "event": "payment.failed",
  "transaction_id": "txn_8f3a92c1",
  "payment_reference": "ORD-10245",
  "status": "failed",
  "amount": 149.00,
  "currency": "GBP",
  "failure_reason": "insufficient_funds",
  "created_at": "2026-06-11T15:14:00Z"
}

Your endpoint reads the event type, updates your system accordingly, and responds with a 2xx to acknowledge receipt. That acknowledgement matters — most gateways retry delivery until they get one.

Webhooks vs Polling: Why Events Matter for Payments

You can learn a payment’s state by polling a status endpoint on a schedule, and webhooks pair well with a payment status API for exactly that reason. But polling alone has two problems: it is either too slow (you check every few minutes and miss the moment) or too expensive (you check constantly and waste calls).

Webhooks invert the model. The gateway tells you the instant a state changes, so your fulfilment, reporting and support systems react in near real time rather than on a timer. The robust pattern is to treat webhooks as the trigger and a status query as the confirmation — listen for the event, then verify the current state before acting on anything irreversible.

Core Payment Webhook Events to Track Before Going Live

You do not need every event a gateway can emit, but a handful are non-negotiable. These are the payment webhook events that map directly to decisions your business makes.

Checkout and payment created

The checkout webhook fires when a customer initiates payment and a transaction is created. On its own it confirms nothing financially — the payment is still pending — but it lets you open an order record, attach your payment reference, and start a timeout clock. Treat it as “intent registered”, not “money received”.

Payment approved or succeeded

This is the event most teams build first: authorisation succeeded. Crucially, approved is not the same as settled — the funds are reserved, not yet in your account. Use this event to mark an order as authorised, but keep final accounting tied to settlement.

Failed and declined payments

A failed payment webhook is one of the most valuable events you can handle, because it carries a failure_reason. A technical failure (timeout, gateway error) often justifies a retry; a hard decline (do not honour, insufficient funds) usually does not. Routing these correctly is the foundation of sensible payment retry logic — retrying the right failures, on the right schedule, without looking like card testing.

Cancelled, refunded and chargeback

Cancellations close a transaction cleanly. Refund events let support and finance see returned funds without manual checks. Chargeback events are the ones you cannot afford to miss — they start a clock on dispute evidence, and a webhook is often your earliest warning that one has been raised.

Settlement

The settlement webhook tells you funds have cleared and are on their way to your balance. For finance, this is the event that turns “approved” into “paid”, and it is what makes automated reconciliation possible.

The Checkout Webhook: Confirming Intent, Not Payment

It is worth dwelling on the checkout event because it is so often misused. Because it arrives first, teams are tempted to treat it as confirmation and trigger fulfilment from it. That is how goods get shipped against payments that never complete.

The safer design: let the checkout webhook create the order in a pending state, and let only the approved (and ideally settled) events advance it. The first event opens the story; it does not end it.

Failed Payment Webhooks and Retry Logic

The failed payment webhook earns its place by carrying context. “Not paid” is useless on its own; “not paid because the issuer timed out” tells you to retry, while “not paid because the card is reported lost” tells you to stop and prompt for a new method.

Wiring this event into your retry strategy means decisions are driven by the actual failure reason rather than a blanket “try again three times”. It also feeds clearer customer messaging — telling someone their card was declined is far better than a generic error, and it cuts the support tickets that vague failures generate.

Settlement Webhooks: Knowing When Money Actually Lands

Authorisation and settlement are different moments, and only one of them puts money in your account. A settlement webhook closes that gap automatically.

When a settlement event arrives — typically with a settlement reference and an amount — you can match it against the original transaction, confirm payout, and update your ledger without anyone exporting a CSV. For teams running monthly reconciliation, this single event turns a manual chase into a routine reconciliation check, and it is the natural complement to tracking transaction status through the rest of the flow.

Designing Reliable Webhook Handling

Receiving events is easy. Handling them reliably is where integrations succeed or fail before launch. A few principles matter more than the rest:

• Verify signatures. Treat every incoming webhook as untrusted until you have validated its signature against your signing secret. Unverified endpoints are an obvious attack surface.
• Be idempotent. Gateways retry delivery, so the same event can arrive more than once. Key your processing on the event or transaction ID so a duplicate does nothing twice.
• Respond fast, process async. Acknowledge with a 2xx quickly, then do the heavy work in a background job. Slow handlers look like failures and trigger retries.
• Do not assume order. Events can arrive out of sequence — a settlement before its approval, in rare cases. Reconcile against current state rather than trusting arrival order.
• Log everything. A stored history of raw events is invaluable when reconciling or debugging a disputed payment.

Webhooks Across Multiple Processors

If you route payments through more than one provider — for redundancy or better approval rates — each one sends its own webhooks, in its own format. Without a layer to normalise them, your endpoint becomes a tangle of provider-specific special cases.

This is where payment orchestration helps: it consolidates events from multiple routes into one consistent event stream and status model, so your application reasons about “a payment failed” rather than “processor B sent its particular failure shape”. The more processors you add, the more that normalisation is worth.

A Pre-Launch Webhook Checklist

Before you go live, walk through this short list:

• Endpoint is publicly reachable over HTTPS and returns 2xx on success.
• Signature verification is enforced on every event.
• Handlers are idempotent and safe against duplicate delivery.
• Checkout, approved, failed, declined, refunded, chargeback and settlement events are all handled — not just the happy path.
• Failed events route into your retry logic by failure reason.
• Raw events are logged and retryable from your side if processing fails.
• You have tested with real sandbox events, including out-of-order and repeated deliveries.

If every box is ticked, most of the “it worked in testing” surprises disappear.

How Niftipay Handles Payment Webhooks

Niftipay is designed so that the events above arrive as one clean, consistent stream rather than a per-provider patchwork. Checkout, approval, failure, refund, chargeback and settlement events share a common shape, are signed for verification, and are retried until your endpoint acknowledges them — so a momentary outage on your side does not lose data.

For high-risk and complex businesses, that consistency is what lets a small team run a reliable integration: failures carry reasons you can act on, settlement events close the reconciliation loop, and the same data powers support, fulfilment and finance at once.

The mindset that keeps webhook integrations healthy is simple — build your endpoint to be a sceptic. Verify before you trust, confirm before you act, and assume any event might arrive twice, late, or out of order. Design for that, and going live stops being the moment you discover what you forgot to listen for.