Payout Webhooks

Instead of polling, let PayRam push status changes to you. Whenever a payout transitions, PayRam POSTs a JSON event to your registered webhook URL — so you learn about sent, processed, failed, etc. as they happen.

Requires PayRam v3.1.1 or later.

Setup

1. Register your webhook URL in the dashboard for the project (Project → Webhooks) and set it to active.

2. The endpoint must be a publicly reachable HTTPS URL that responds with a 2xx status.

Webhooks are on by default. (They can be disabled server-side with the SEND_WEBHOOK_TO_MERCHANT=false environment variable.)

Delivery & retries

• Method: POST, Content-Type: application/json.

• Verify authenticity of every delivery using either header:

  • X-Payram-Signature (recommended) — an HMAC-SHA256 of the raw request body, keyed with your project API key, formatted sha256=<hex>. Recompute it on your side and constant-time compare.

  • API-KEY — your project API key sent verbatim (legacy; kept for backward compatibility).

• Each delivery is retried up to 3 times (immediately, then after 2s and 4s) until your endpoint returns a 2xx. Any response ≥ 400 (or a timeout — the client waits up to 60s) counts as a failure.

• The payout’s webhookStatus becomes received once your endpoint accepts a delivery, or failed if all attempts fail.

• Return 2xx quickly and process asynchronously; treat events as idempotent (you may receive the same status more than once) and key off payout_id + status.

Verifying the signature

Compute the HMAC over the exact raw bytes of the request body (do not re-serialize the parsed JSON) and compare against the X-Payram-Signature header:

const crypto = require('crypto');

function verifyPayramSignature(rawBody, signatureHeader, apiKey) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', apiKey).update(rawBody).digest('hex');
  // constant-time compare
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

Event types

The event_type is payout.<status> (lowercase). Note the status is the webhook status label, which maps from the payout’s lifecycle state:

Payout status (API)	Webhook status	event_type
pending-approval / pending-otp-verification	PENDING-APPROVAL	payout.pending-approval
pending	APPROVED	payout.approved
initiated	INITIATED	payout.initiated
sent	SENT	payout.sent
processed	PROCESSED	payout.processed
failed	FAILED	payout.failed
rejected	REJECTED	payout.rejected
cancelled	CANCELLED	payout.cancelled

Payload

{
  "event_type": "payout.sent",
  "payout_id": 120,
  "network": "ETH",
  "token": "USDC",
  "amount": "100",
  "amount_usd": "100.000000",
  "email": "[e-mail]",
  "address": "0x9F8E7D6C5B4A39281706F5E4D3C2B1A098765432",
  "from_address": "0x21d4cF2E…EA8d45",
  "tx_hash": "0xabc123…def456",
  "status": "SENT",
  "withdrawal_type": "payout_merchant",
  "currency_type": "token",
  "created_at": 1750340081,
  "updated_at": 1750340282,
  "timestamp": 1750340282,
  "failure_reason": ""
}

Field	Meaning
event_type	payout.<status> — the event that fired.
payout_id	The payout id (matches the id from Create / Get Payout).
network / token	Blockchain code and currency.
amount / amount_usd	Crypto amount sent and its USD value.
email / address	Recipient email and destination wallet address.
from_address	Project hot wallet that paid out (empty until assigned).
tx_hash	On-chain hash (empty until initiated).
status	Uppercase webhook status (see the mapping table).
withdrawal_type	payout_merchant for payouts created via this API.
currency_type	token (ERC20/TRC20) or coin (native ETH/POL/TRX).
created_at / updated_at / timestamp	Unix epoch seconds.
failure_reason	Reason string on payout.failed (empty otherwise).

Always respond 2xx to acknowledge. If your endpoint is unreachable or errors, PayRam marks the delivery failed after retries — you can still reconcile via Get All Payouts / Payout Status.