Gareth Wilson Gareth Wilson

Guide to OxaPay Webhooks: Features and Best Practices

Published


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

FeatureDetails
Configurationcallback_url on each payment or payout request
Signaturehex HMAC-SHA512
Signature headerhmac
Signed contentThe raw request body
KeyMERCHANT_API_KEY (payments) or PAYOUT_API_KEY (payouts)
BodyJSON transaction state
Event routingBody field status (flow in type)
Success responseHTTP 200 with body ok
RetriesUp to 5 attempts: after ~1 min, 3 min, 30 min, 3 h
NetworkPublic URLs only; IP list by email

Events and payloads

statusFlowTriggered WhenCommon Use Cases
PayingPaymentPayer transferred funds; awaiting network confirmationMark the order as in progress; do not deliver yet
PaidPaymentNetwork confirmed and the merchant was creditedFulfil the order, grant access
ConfirmingPayoutPayout sent; awaiting network confirmationMark the payout as sent
ConfirmedPayoutPayout confirmed by the networkMark the payout as completed
FailedPayoutPayout failedAlert, 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 ok immediately, 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 ok explicitly, 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 Paid as 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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.