Payout Webhooks

PayRam POSTs a JSON event to your webhook URL each time a payout changes status, so you don’t have to poll. Requires PayRam v3.1.1 or later.

Setup

Register an HTTPS URL for the project in the dashboard (Project → Webhooks) and set it to active. It must be publicly reachable and answer 2xx.

Which payouts send webhooks

Every merchant payout — API and dashboard. Dashboard payouts send their full lifecycle (PayRam Core v3.9.0 and later). The payload’s created_by field tells them apart: user for API payouts, system for dashboard payouts (PayRam Core v3.9.0 and later). Referral payouts do not send webhooks.

Event types

event_type	status	Meaning
payout.pending-approval	PENDING-APPROVAL	Created and held for approval. Sent again when an admin approves, while the approval code is awaited.
payout.approved	APPROVED	Queued to send (API status pending).
payout.initiated	INITIATED	Broadcast; tx_hash set.
payout.sent	SENT	Confirmed on chain — success. Carries the final tx_hash.
payout.failed	FAILED	Did not go through; see failure_reason.
payout.rejected	REJECTED	Rejected by an admin.
payout.cancelled	CANCELLED	Cancelled before sending.

There is no payout.pending and no payout.processed event — treat payout.sent as the final success event.

Payload

The body is snake_case JSON; timestamps are Unix seconds.

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

Field	Meaning
event_type	See Event types.
payout_id	The payout id — use it with GET Single Payout.
network / token	Network code and token.
amount / amount_usd	Amount in the token, and its USD value at creation.
email	Recipient email.
address	Recipient wallet.
from_address	Project hot wallet the payout is sent from.
tx_hash	Transaction hash; empty until initiated. Can change while initiated — keep the latest.
status	Uppercase status (see Event types).
withdrawal_type	Always payout_merchant.
created_by	user (API payout) or system (dashboard payout). (PayRam Core v3.9.0 and later)
currency_type	token or coin (native ETH, POL, TRX).
created_at / updated_at / timestamp	Unix seconds; timestamp equals updated_at.
failure_reason	Reason on payout.failed and payout.rejected; empty otherwise.

Verifying the signature

Each delivery carries X-Payram-Signature: sha256=<hex> — an HMAC-SHA256 of the raw request body, keyed with your project API key. The legacy API-KEY header (your key, verbatim) is also sent. Compute the HMAC over the exact raw bytes, not re-serialized JSON:

const crypto = require('crypto');

function verifyPayramSignature(rawBody, signatureHeader, apiKey) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', apiKey).update(rawBody).digest('hex');
  const a = Buffer.from(signatureHeader || '');
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Delivery

• Ping first. Before each delivery PayRam POSTs {"event_type": "payout.ping", ...} to each URL. The ping carries X-Webhook-Test: true and is signed like every other webhook (PayRam Core v3.9.0 and later). Answer it 2xx, or that URL is skipped for this event.

• 3 attempts — immediately, after 2s, after 4s. A response of 400 or above, or no response within 60 seconds, counts as a failure. There is no later redelivery: if all attempts fail, reconcile with GET Single Payout. The payout’s webhookStatus shows the last result.

• Be idempotent. Events can repeat. Key on payout_id + status, answer 2xx quickly and process asynchronously.