Invoice Callback
Pronunciation: IN-voys KAWL-bak
Definition
An invoice callback is a server-to-server notification sent to a configured receiver when an invoice or its payment status changes. A reliable Invoice Callback implementation validates authenticity, acknowledges quickly, stores the event durably, processes idempotently, tolerates duplicates and reordering, and records the final business outcome.
Overview
Meaning and scope
An invoice callback is a server-to-server notification sent to a configured receiver when an invoice or its payment status changes. A reliable Invoice Callback implementation validates authenticity, acknowledges quickly, stores the event durably, processes idempotently, tolerates duplicates and reordering, and records the final business outcome.
Mechanism and operation
It enables asynchronous updates when the payer is no longer present in the browser. Callbacks are commonly retried and may be duplicated, delayed, or delivered out of order. Receivers should verify the provider’s authentication mechanism, parse defensively, deduplicate atomically, and validate allowed state transitions. They should acknowledge quickly, process durable work asynchronously, and query authoritative invoice status when uncertain. An invoice callback informs a merchant system about events such as payment detected, confirmation progress, completion, expiration, failure, or another lifecycle change. Replay of Invoice Callback should preserve original identifiers and timestamps so historical processing cannot masquerade as a new event.
Practical payment example
An invoice callback announces a confirmed receipt, and the store cross-checks the invoice identifier and amount before marking the order paid.
Operational checks
An audit trail for Invoice Callback should link the contract and client version, principal, request identifier, sanitized payload evidence, response, callbacks, retries, overrides, provider references, and final state. For Invoice Callback, metrics should separate transport success from business success. Payload fields can also become stale after a later invoice update.
Distinctions and limits
Delivery success proves only that a message reached an endpoint, not that the business action completed. A Invoice Callback handler should acknowledge only after durable receipt when the provider’s retry contract depends on the response. Logs need correlation identifiers without exposed secrets or sensitive payloads.
Related reading
Related definitions: authentication, payment detected.
Example
An invoice callback announces a confirmed receipt, and the store cross-checks the invoice identifier and amount before marking the order paid.
Comparison
Delivery success proves only that a message reached an endpoint, not that the business action completed. A Invoice Callback handler should acknowledge only after durable receipt when the provider's retry contract depends on the response.
Key Takeaway
Invoice callbacks are untrusted asynchronous events until authenticated, deduplicated, validated, and reconciled with authoritative invoice state.
Sources
- OxaPay Documentation: Webhook — OxaPay (2026-07-30)
- Stripe Documentation: Webhooks — Stripe (2026-07-30)