Payment Webhook
Pronunciation: PAY-ment WEB-hook
Definition
A payment webhook is a provider-generated HTTP notification about an event in a payment’s lifecycle, such as detection, confirmation, expiration, refund or payout progress.
Overview
What it means
A payment webhook is a provider-generated HTTP notification about an event in a payment’s lifecycle, such as detection, confirmation, expiration, refund or payout progress. It helps applications react without querying the provider every second.
How it works
The provider sends a structured event to a configured callback URL. The recipient verifies the event signature, deduplicates it, validates the payment reference and updates its own state machine according to permitted transitions. Providers may retry delivery and do not always guarantee event order or exactly-once semantics.
Understanding the technical details
Subscribe only to needed event types and document what each provider status means. An event reporting payment detection can arrive before adequate confirmations; a separate final event may be required for fulfillment. Retries can arrive hours later and order is not always guaranteed. The receiver should track both event identity and current order state, while a periodic status query repairs missing notifications. Treat webhooks as signals that inform a verified state machine, not self-authenticating commands.
Additional protocol context
Delivery is usually at least once and can be delayed, duplicated, reordered, or exhausted after retries. Public endpoints can receive forged or replayed messages. Returning success before durable storage may lose an event when later processing fails.
Receivers should use HTTPS, verify the documented signature or authentication, validate the schema, deduplicate atomically, and persist before acknowledging. Processing should run through durable queues and legal state transitions. Replay tools, monitoring, status queries, and reconciliation cover delivery gaps.
Common failures and limitations
A webhook is not a bank statement or a final settlement guarantee. The merchant must interpret what the provider’s status actually means and reconcile against authoritative records, especially after missed events or outages.
Related concepts
Webhook, Webhook Verification, Merchant API Key.
Further reading
Example
A store receives a “paid” event for an invoice and grants a digital download after validating it. A duplicate delivered five minutes later produces no additional license because the event and order state were already recorded.
Comparison
A payment webhook is a push notification. A Payment Status API is a pull-based query interface; using both provides faster updates and a recovery path when notifications are missed.
Key Takeaway
A webhook is not a bank statement or a final settlement guarantee.
Sources
- IETF RFC 9110 — IETF (2026-07-30)
- OpenAPI Initiative Documentation: V3.2.0 — OpenAPI Initiative (2026-07-30)
- OxaPay Documentation: Webhook — OxaPay (2026-07-30)