Webhook

Overview

Why the provider calls your server

A webhook is an HTTP message that a service sends to your application when something happens. In crypto payments it can report changes such as a detected payment, confirmation or payout status. The alternative is for your application to ask the provider every few seconds whether anything has changed. Webhooks reduce that repetitive polling, but they introduce delivery challenges. Networks time out, servers restart and the same notification may be sent more than once. A webhook is therefore a notification channel, not an infallible transaction ledger.

How the underlying system works

With a webhook integration, the merchant exposes an HTTPS endpoint and configures a callback URL. When the provider observes an event, it sends an HTTP request containing structured data. The receiver should authenticate the request, persist an event or durable job, return an appropriate response promptly and process business effects in an idempotent worker. A failed connection can cause retries; two messages may describe the same state.

OxaPay documents signed webhook callbacks and a delivery retry policy. An integration should follow its current authentication format, not rely on source IP or the presence of a transaction hash as the sole authenticity test. After validation, map the event to an invoice and obtain any additional details needed for fulfillment from trusted records. Keep event IDs or a stable deduplication key where available.

Build a safe receiving workflow

When a callback arrives, the server first obtains the raw request body and checks any provider signature using the correct secret. It then validates the expected event type, identifiers and data shape. Instead of making slow business changes inside the HTTP request, it can record the event in a durable queue and acknowledge valid receipt promptly. A background worker then checks whether this event was handled before and updates the invoice only when the current business rules allow it. If the callback is missed, the service should still be able to query payment status and reconcile outstanding invoices.

Why browser redirects are not replacements

A browser redirect occurs on the customer's device. The customer can close the page, lose connectivity or visit the success URL without a matching completed payment. Only authenticated server-side evidence should influence fulfillment. For OxaPay, the webhook documentation describes a raw-body HMAC-SHA512 signature and a HMAC HTTP header for callback validation. Signature checks authenticate the message, while invoice matching and status validation determine what it means for a particular order. These are different responsibilities that a secure receiver performs in sequence.

Further reading and related concepts

Reference documents: OxaPay — Webhook.

Related glossary topics: Webhook Signature, Webhook Verification, Webhook Retry.