Agent skill

OxaPay Webhooks Skill

Receive and verify OxaPay webhooks (crypto payment callbacks). Use when setting up an OxaPay callback_url handler, verifying the HMAC header (hex HMAC-SHA512 of the raw body), debugging OxaPay signature verification failures, replying with the required "ok" body, or handling payment and payout statuses like Paying, Paid, Confirming, Confirmed and Failed.

Install this skill

npx skills add hookdeck/webhook-skills --skill 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.

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/, examples/nextjs/, 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).

statusFlowMeaning
PayingPaymentPayer sent funds; awaiting blockchain confirmation. Do not deliver goods yet
PaidPaymentConfirmed by the network and credited to the merchant; safe to fulfil
ConfirmingPayoutPayout sent; awaiting blockchain confirmation
ConfirmedPayoutPayout confirmed by the network
FailedPayoutPayout 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

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:

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

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →