Guide to OxaPay Webhooks: Features and Best Practices
OxaPay is a crypto payment gateway for merchants who want to accept and send cryptocurrency: hosted invoices, white-label payment pages, static deposit addresses, payment links, donations and payouts. Blockchain payments confirm in stages and can take minutes, so OxaPay posts a callback each time a transaction's state changes, and those callbacks decide when your shop can safely deliver.
This guide covers how OxaPay callbacks are attached to each request, the payment and payout statuses, the two API keys used for signing, the ok response OxaPay insists on, and the retry schedule.
What are OxaPay webhooks?
OxaPay has no webhook settings page. Instead, every payment or payout request you make through the API can include a callback_url. When that transaction's state changes, OxaPay sends a JSON POST there. OxaPay won't call private network addresses such as localhost.
Each callback is the transaction's current state, with no event name. status says what happened (for example Paying then Paid), and type says which flow it belongs to.
Callbacks are signed with HMAC-SHA512 in a header called simply HMAC. The key depends on the flow: your merchant API key for payments and your payout API key for payouts.
OxaPay webhook features
| Feature | Details |
|---|---|
| Configuration | callback_url on each payment or payout request |
| Signature | hex HMAC-SHA512 |
| Signature header | hmac |
| Signed content | The raw request body |
| Key | MERCHANT_API_KEY (payments) or PAYOUT_API_KEY (payouts) |
| Body | JSON transaction state |
| Event routing | Body field status (flow in type) |
| Success response | HTTP 200 with body ok |
| Retries | Up to 5 attempts: after ~1 min, 3 min, 30 min, 3 h |
| Network | Public URLs only; IP list by email |
Events and payloads
status | Flow | Triggered When | Common Use Cases |
|---|---|---|---|
Paying | Payment | Payer transferred funds; awaiting network confirmation | Mark the order as in progress; do not deliver yet |
Paid | Payment | Network confirmed and the merchant was credited | Fulfil the order, grant access |
Confirming | Payout | Payout sent; awaiting network confirmation | Mark the payout as sent |
Confirmed | Payout | Payout confirmed by the network | Mark the payout as completed |
Failed | Payout | Payout failed | Alert, release or retry |
A payment produces a Paying callback when the payer's transfer is seen and a second Paid callback once the network confirms it and your balance is credited. Only Paid means goods can be delivered. OxaPay's examples capitalise these values while its prose writes "paying" and "paid", and no full list of statuses is published, so compare case-insensitively and log anything else, such as an expiry.
Event Payload Structure
All callbacks share track_id, status, type, amount, value, currency and date. type is invoice, white_label, static_address, payment_link or donation for payments, and payout for payouts.
Payment callbacks add order_id, email, fee fields and a txs array of the blockchain transactions involved; the status inside each txs entry is lowercase (confirming, confirmed). Payout callbacks add tx_hash, address and network.
OxaPay's examples annotate values with types (for example "amount":10, decimal), so they aren't valid JSON. Capture a real callback to build fixtures.
Setting up OxaPay webhooks
Prerequisites
- An OxaPay merchant account
- Your merchant API key (payment callbacks) and/or payout API key (payout callbacks)
- A public HTTPS endpoint
Get Your Signing Secret
OxaPay has no separate webhook secret. It signs with your API keys:
- Payment callbacks (invoice, white-label, static address, payment link, donation): your
MERCHANT_API_KEY - Payout callbacks: your
PAYOUT_API_KEY
Paste your merchant API key for payment callbacks, or your payout API key for payout callbacks, and use a separate source for each. OxaPay expects an "ok" response body, so set the source's custom response to ok.
For a direct receiver, run one verifier per key, ideally on separate paths such as /webhooks/oxapay/payments and /webhooks/oxapay/payouts.
Register Your Endpoint
Set callback_url in each payment or payout request, for example https://example.com/webhooks/oxapay. If Cloudflare or another firewall sits in front of your server, ask OxaPay (contact@oxapay.com) for its IP addresses and allow them.
Test a delivery
Start a local receiver and forward requests with the Hookdeck CLI:
npx hookdeck-cli listen 3000 oxapay --path /webhooks/oxapay
OxaPay won't call localhost, so use the CLI's public URL as callback_url on a small test invoice. You should see Paying, then Paid.
Securing OxaPay webhooks
Compute HMAC-SHA512 of the raw body with the relevant API key, hex-encode it, and compare it with the HMAC header in constant time. OxaPay's samples choose the key from data.type after parsing, and its Node and Python versions test type === 'payment', a value payment callbacks never carry (they use invoice and so on), so as written they'd use the payout key for payments. Separate endpoints avoid the problem. See the webhook documentation.
const crypto = require('node:crypto');
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['hmac'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const message = rawBody;
const candidates = [signature];
const expected = crypto.createHmac('sha512', key).update(message).digest();
return candidates.some((candidate) => {
if (!/^[0-9a-fA-F]{128}$/.test(candidate)) return false;
const received = Buffer.from(candidate, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
This handler serves payment callbacks, deduplicates on track_id plus status, and replies with the ok body OxaPay requires.
const express = require('express');
function createOxaPayPaymentsApp({ alreadyApplied, orders }) {
const app = express();
app.post('/webhooks/oxapay/payments', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
let callback;
try {
callback = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!callback || typeof callback !== 'object' || Array.isArray(callback)) {
return res.sendStatus(400);
}
if (!callback.track_id || callback.status === undefined) return res.sendStatus(400);
const status = String(callback.status).toLowerCase();
try {
if (!(await alreadyApplied(`${callback.track_id}:${status}`))) {
if (status === 'paying') await orders.markAwaitingConfirmation(callback.order_id, callback.track_id);
else if (status === 'paid') await orders.fulfil(callback.order_id, callback.amount, callback.currency);
else console.log('Unhandled OxaPay status', callback.status, callback.type);
}
} catch {
return res.sendStatus(503);
}
return res.status(200).send('ok');
});
return app;
}
Run a second copy for payouts with PAYOUT_API_KEY as its secret and handlers for Confirming, Confirmed and Failed.
Only the body is signed, and it carries no signed time, so a captured callback can be replayed. The track_id and status key makes a replay a no-op.
Hookdeck's OxaPay source type verifies the HMAC header as a hex HMAC-SHA512 of the raw body with the key you paste. It answers OxaPay with 200 (and ok once you set the custom response), records a mismatch as failed verification and doesn't forward it. No timestamp tolerance applies.
Make OxaPay webhooks production-ready. Hookdeck Event Gateway gives OxaPay a public URL that answers
okimmediately, verifies payments and payouts with separate sources, and keeps every callback replayable after OxaPay's five attempts end.
OxaPay webhook limitations and pain points
A specific response body
The Problem: Callbacks are retried even though your endpoint returned 200.
Why It Happens: OxaPay treats a delivery as successful only when the response is HTTP 200 with the body ok. Many frameworks return OK, JSON or an empty body by default.
Workarounds:
- Send
okexplicitly, as in the handler above.
How Hookdeck Can Help: Set the OxaPay source's custom response to ok, and Hookdeck returns it for every callback regardless of what your service replies.
Two signing keys
The Problem: Payment or payout callbacks fail verification.
Why It Happens: Payments are signed with the merchant API key and payouts with the payout API key, and OxaPay's own sample code picks the wrong one for payments.
Workarounds:
- Use separate callback URLs and verifiers for payments and payouts.
How Hookdeck Can Help: Two Hookdeck sources, one per key, keep the verification separate while delivering to the same service if you like.
Five attempts in about three and a half hours
The Problem: A longer outage loses a Paid callback, leaving a customer who paid without their order.
Why It Happens: OxaPay gives up after five attempts, the last about three and a half hours after the first.
Workarounds:
- Query open invoices through OxaPay's API after any downtime.
How Hookdeck Can Help: Hookdeck accepts the callback on the first attempt and retries your service for as long as you configure.
Undocumented statuses
The Problem: An expired or underpaid invoice arrives with a status your code doesn't handle.
Why It Happens: OxaPay publishes no full status table, only the values in its examples.
Workarounds:
- Log and store unknown statuses, and never treat anything other than
Paidas settled.
How Hookdeck Can Help: Hookdeck filters on status can send only Paid callbacks to fulfilment and everything else to a review queue.
Best practices
Use callback_url consistently
Since the URL is set per request, keep it in one configuration value used by every payment and payout call, ideally a stable Hookdeck source URL.
Wait for Paid
Paying means a transfer was seen, not confirmed. Hold delivery until Paid.
Answer fast, then fulfil
OxaPay doesn't state a timeout. Store the callback, reply ok, and fulfil in the background as our asynchronous processing guide describes.
Key on track_id and status
Each status change is its own callback, and retries repeat it. Store that pair with the order update, following the idempotency guide.
Conclusion
OxaPay's callbacks report each step of a crypto payment or payout, signed with HMAC-SHA512. To run them reliably, reply with exactly ok, keep payments and payouts on separate keys and endpoints, wait for Paid, and plan for the five-attempt limit.
Hookdeck Event Gateway handles the ok response, the two keys and the retries in front of your service.
Get started with Hookdeck for free and handle OxaPay webhooks reliably in minutes.