# 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](/docs/cli):

```bash
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](https://docs.oxapay.com/webhook).

```javascript
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.

```javascript
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](/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](/webhooks/guides/why-implement-asynchronous-processing-webhooks) 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](/webhooks/guides/implement-webhook-idempotency).

## 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](https://hookdeck.com) handles the `ok` response, the two keys and the retries in front of your service.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle OxaPay webhooks reliably in minutes.