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
HMACheader 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,ConfirmedandFailedcallbacks?
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.jsawait request.arrayBuffer(); in FastAPIawait request.body(). Parse JSON only after the check. - Missing, empty, malformed or mismatching
HMAC: respond401. - OxaPay's own samples compare with
===/==and pick the key fromdata.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).
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
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
- references/overview.md - OxaPay callbacks, statuses, payload fields, retries
- references/setup.md - Set the callback_url, choose the right key, Hookdeck source
- references/verification.md - HMAC-SHA512 details, gotchas, debugging