# OxaPay Webhooks

## When to Use This Skill

* How do I receive OxaPay webhooks on my `callback_url`?
* How do I verify the OxaPay `HMAC` header signature?
* Why is my OxaPay webhook signature verification failing, or why does OxaPay keep retrying?
* Which key signs payment callbacks and which signs payout callbacks?
* How do I handle `Paying`, `Paid`, `Confirming`, `Confirmed` and `Failed` callbacks?

## Verification (core)

OxaPay sends one header, `HMAC`, holding the **lowercase hex HMAC-SHA512 of the raw request body** (128 hex characters, no prefix). The key is your **merchant API key** for payment callbacks or your **payout API key** for payout callbacks, used as-is as UTF-8 bytes. Nothing else is signed: no timestamp, id or other header, so there is no replay window to check.

```javascript
const crypto = require('crypto');

function verifyOxapaySignature(rawBody, signature, secret) {   // rawBody: Buffer
  if (!signature || !secret || !/^[0-9a-fA-F]{128}$/.test(signature)) return false;
  const expected = crypto.createHmac('sha512', secret).update(rawBody).digest();
  const received = Buffer.from(signature, 'hex');               // format validated above
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

```

* Verify the exact bytes received. In Express use `express.raw({ type: '*/*' })`; in Next.js `await request.arrayBuffer()`; in FastAPI `await request.body()`. Parse JSON only after the check.
* Missing, empty, malformed or mismatching `HMAC`: respond `401`.
* OxaPay's own samples compare with `===`/`==` and pick the key from `data.type`; use a constant-time compare and one secret per deployment instead.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/oxapay-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/oxapay-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/oxapay-webhooks/examples/fastapi/).

## Respond with `ok`

OxaPay counts a delivery as successful only when the response is **HTTP 200 with the body `ok`**. Anything else is retried, up to 5 attempts in total: about 1 minute, then 3 minutes, 30 minutes and 3 hours after the previous attempt. The examples answer a verified callback with `200` and the plain-text body `ok`.

## Hookdeck setup note

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.

## Common Event Types

OxaPay sends no event name and no event header. Each callback is the transaction's current state: dispatch on the body's `status`. `type` says which flow it is (`invoice`, `white_label`, `static_address`, `payment_link`, `donation` for payments; `payout` for payouts).

| `status` | Flow | Meaning |
| --- | --- | --- |
| `Paying` | Payment | Payer sent funds; awaiting blockchain confirmation. Do not deliver goods yet |
| `Paid` | Payment | Confirmed by the network and credited to the merchant; safe to fulfil |
| `Confirming` | Payout | Payout sent; awaiting blockchain confirmation |
| `Confirmed` | Payout | Payout confirmed by the network |
| `Failed` | Payout | Payout failed |

The examples capitalise the status (`"Paid"`) while the prose writes "paid"; the handlers match the documented spelling and log anything else. Per-transaction `txs[].status` values are lowercase (`confirming`, `confirmed`).

## Environment Variables

```bash
OXAPAY_WEBHOOK_SECRET=your_oxapay_api_key   # merchant API key (payments) or payout API key (payouts)

```

## Local Development

OxaPay does not send callbacks to private networks such as localhost, so use a tunnel:

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 oxapay --path /webhooks/oxapay

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/oxapay-webhooks/references/overview.md) - OxaPay callbacks, statuses, payload fields, retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/oxapay-webhooks/references/setup.md) - Set the callback_url, choose the right key, Hookdeck source
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/oxapay-webhooks/references/verification.md) - HMAC-SHA512 details, gotchas, debugging