Webhook Retry

Overview

Retries are normal, not necessarily a service failure

A provider sends a webhook but does not receive a satisfactory response. Perhaps the merchant server is restarting, a firewall blocks the request, or the network connection breaks after the merchant has already saved the event. The provider cannot always know whether the business action happened, so it may retry delivery. This creates a key rule: callbacks should be expected more than once. Exactly-once arrival is not a safe assumption for internet messaging, even when the same invoice was paid only once.

How the underlying system works

A webhook provider cannot always tell whether a consumer completed its work: the consumer might commit an order update and lose the HTTP response. The provider may then send the event again. OxaPay documents multiple delivery attempts with increasing delays for unsuccessful callbacks, but integrations should consult the current provider policy instead of hard-coding timing assumptions.

The correct receiver behavior is to validate each attempt, record it safely and make its business effect idempotent. A database uniqueness constraint on a provider event or invoice transition can prevent two fulfillment actions. Delivery retries are not a substitute for reconciliation; after an extended outage, query payment records to identify events the application may have missed. Monitor attempt counts, invalid-signature failures and the age of unprocessed events.

A duplicate-notification story

A customer's payment becomes accepted. The provider sends a callback, your app records it and releases a download. Right before your server responds, the connection drops. The provider retries and sends the same status again. A naïve handler releases the download twice or triggers a second affiliate commission. A robust handler stores a unique event or invoice-state transition and checks it before any irreversible action. It may acknowledge the duplicate as already handled while preserving the single fulfillment record. Transaction evidence and business-state transitions need their own stable IDs.

Recovery when notifications never arrive

Delivery retries have practical limits, and the exact schedule is provider-specific. OxaPay documents retry behavior, but integration code should not depend on a promised exact delay unless the current contract guarantees it. Run a periodic reconciliation job for invoices stuck in waiting or confirming states; query the provider's authoritative status and repair missed transitions. Monitor callback endpoint availability, signature failures and the rate of repeated deliveries. A webhook mechanism is reliable only when retries, deduplication and reconciliation work together.

Further reading and related concepts

Reference documents: OxaPay — Webhook.

Related glossary topics: Webhook, Webhook Verification, Payment Status API.