Webhooks

Webhooks push real-time events to your backend. This page documents the exact payload Rach sends for every event, the headers, and how to verify signatures. Payments and CaaS each have their own configuration and signature scheme.

Escrow notifications use an event_id, event, created_at, data envelope with persistent retries and tenant-scoped replay. Deduplicate by event ID and verify the CaaS signature. See escrow webhooks.

Payments webhooks

Configure your endpoint

Set your webhook URL (and enable wallet/deposit events) in the Payments dashboard under Developers → Webhooks. The dashboard shows your signing secret (whsec_…) once — store it to verify signatures.

The webhook_secret (whsec_…) is shown only when you set or rotate it in the dashboard. Store it — you need it to verify signatures. Rotating it invalidates the old one.

Headers on every delivery

Header	Value
`X-Webhook-Signature`	`HMAC-SHA256(rawBody, webhook_secret)`, hex-encoded
`X-Webhook-Event`	The event name (e.g. `payment.confirmed`)
`X-Webhook-ID`	The delivery id — dedupe on this
`Content-Type`	`application/json`

Events & exact payloads

There are two payload shapes: checkout/remittance events are flat; wallet (WaaS) events wrap the data in an event + data envelope.

payment.confirmed / payment.failed
wallet.deposit.detected
wallet.deposit.confirmed
wallet.deposit.hash_resolved
wallet.transfer.*

Sent for Crypto Gateway checkout sessions. Flat payload:

{
  "event": "payment.confirmed",
  "session_id": "cs_1a2b3c",
  "reference": "order_1001",
  "amount": "50",
  "currency": "USD",
  "status": "paid",
  "payment_method": "crypto",
  "network": "ETH",
  "tx_hash": "0x9f8e7d6c5b4a...",
  "created_at": "2026-08-14T12:00:00Z",
  "paid_at": "2026-08-14T12:41:00Z",
  "metadata": { "cart_id": "9f3" },
  "timestamp": 1755172860
}

network, tx_hash, paid_at and metadata are omitted when not applicable. payment.failed carries the same shape with status: "failed" and no paid_at.

Sent the moment a monitored WaaS address receives funds. This records a pending deposit — it does not credit. Enveloped payload:

{
  "event": "wallet.deposit.detected",
  "data": {
    "customer_id": "eb0a15c6-57f7-49d5-9b55-fcebaa99ba6d",
    "deposit_id": 48213,
    "address": "0x3B7A3DfC43A6D91f2F6dFEeE2ad9def7141c0586",
    "network": "POL",
    "currency": "USDT",
    "amount": "10",
    "tx_hash": "pending_1755345600_0x3B7A3D",
    "hash_pending": true,
    "confirmations": 0,
    "status": "detected",
    "detected_at": "2026-08-16T12:00:00Z",
    "detected_by": "monitor"
  }
}

Dedupe on deposit_id (the stable idempotency key), not tx_hash — at this stage tx_hash is a pending_<ts>_<addr> placeholder. Do not credit on detected; wait for wallet.deposit.confirmed with safe_to_credit: true.

Sent once the deposit reaches the required confirmations. This is the event that credits — and only when safe_to_credit is true. Note tx_hash is still the pending_… placeholder here; the real chain hash arrives later via hash_resolved.

{
  "event": "wallet.deposit.confirmed",
  "data": {
    "customer_id": "eb0a15c6-57f7-49d5-9b55-fcebaa99ba6d",
    "deposit_id": 48213,
    "address": "0x3B7A3DfC43A6D91f2F6dFEeE2ad9def7141c0586",
    "network": "POL",
    "currency": "USDT",
    "amount": "10",
    "tx_hash": "pending_1755345600_0x3B7A3D",
    "confirmations": 128,
    "status": "confirmed",
    "safe_to_credit": true,
    "detected_at": "2026-08-16T12:00:00Z",
    "confirmed_at": "2026-08-16T12:03:20Z"
  }
}

Credit the customer only when safe_to_credit is true. Key the credit on deposit_id so a re-delivery is a no-op.

Delivered later, once the real on-chain hash is known. Same deposit_id — use it to upgrade the pending_… placeholder you stored to the real explorer-lookupable hash:

{
  "event": "wallet.deposit.hash_resolved",
  "data": {
    "customer_id": "eb0a15c6-57f7-49d5-9b55-fcebaa99ba6d",
    "deposit_id": 48213,
    "tx_hash": "0x9a1f5c2b…",
    "detected_at": "2026-08-16T12:00:00Z"
  }
}

This event does not credit and does not carry amount/currency — it only backfills the hash. Match it to the deposit you already recorded by deposit_id.

Sent as a WaaS wallet transfer you initiated advances (e.g. wallet.transfer.confirmed):

{
  "event": "wallet.transfer.confirmed",
  "data": {
    "tx_hash": "0x1a2b3c...",
    "customer_id": "cust_001",
    "network": "ETH",
    "currency": "USDT",
    "from_address": "0xAbC123...",
    "to_address": "0xRecipient...",
    "amount": "25.00",
    "gas_fee": "0.00031",
    "status": "confirmed",
    "confirmed_at": "2026-08-14T12:06:00Z",
    "block_number": 20553114
  }
}

Deposit `data` — field reference

Field	Type	Notes
`customer_id`	string	The only guaranteed field. Your Rach customer UUID — the deposit’s owner.
`deposit_id`	integer	The idempotency key — dedupe on this, not `tx_hash`.
`address`	string	The receiving derived address.
`network` / `currency`	string	e.g. `POL` / `USDT`.
`amount`	string	A decimal string, e.g. `"10"` (never a number).
`tx_hash`	string	Provisional `pending_<ts>_<addr>` on `detected`/`confirmed`; the real chain hash arrives via `hash_resolved`.
`hash_pending`	bool	`true` = the real hash will arrive later.
`confirmations`	integer	Chain confirmations so far.
`detected_at`	string (ISO)	Stable key linking `detected` → `confirmed` → `hash_resolved` for the same deposit.
`confirmed_at`	string (ISO)	Present on `confirmed`.
`safe_to_credit`	bool	The gate — credit the balance only on `confirmed` when this is `true`.
`status`	string	`"detected"` or `"confirmed"`.

Gotchas

tx_hash is not a real hash at detect/confirm time — it’s a pending_… placeholder. Don’t key anything on it; use deposit_id. The real hash backfills via hash_resolved (same deposit_id).
Crediting is gated on safe_to_credit: true on the confirmed event. detected only records a pending deposit.
Everything except customer_id is technically optional in the serializer, so a malformed/partial event won’t 400 — but a genuine deposit carries the full set above.
The handler is idempotent — re-delivering the same deposit_id is acknowledged with 200 {"status":"success","message":"already_recorded"}.

Verify the signature

Compute the HMAC over the raw body and compare in constant time:

import express from 'express';
import crypto from 'node:crypto';

const app = express();
app.use('/webhooks/rach', express.raw({ type: '*/*' })); // RAW body

app.post('/webhooks/rach', (req, res) => {
  const sig = req.header('X-Webhook-Signature');
  const expected = crypto
    .createHmac('sha256', process.env.RACH_WEBHOOK_SECRET)
    .update(req.body) // Buffer of the raw body
    .digest('hex');

  if (!sig || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('bad signature');
  }

  const { event } = JSON.parse(req.body.toString());
  // dedupe on req.header('X-Webhook-ID'), then process async
  res.sendStatus(200);
});

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhooks/rach")
def rach_webhook():
    raw = request.get_data()  # raw bytes
    expected = hmac.new(
        os.environ["RACH_WEBHOOK_SECRET"].encode(), raw, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(request.headers.get("X-Webhook-Signature", ""), expected):
        abort(401)
    # dedupe on request.headers["X-Webhook-ID"], then process
    return "", 200

func verify(rawBody []byte, sigHeader, secret string) bool {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(rawBody)
	expected := hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(sigHeader), []byte(expected))
}

Test it

Send a test event and rotate your signing secret from the Payments dashboard (Developers → Webhooks). Rotating invalidates the old secret — update your verifier immediately.

CaaS webhooks

Delivery & verification (every event)

Every webhook is an HTTP POST with a JSON body and these headers:

Header	Value
`Content-Type`	`application/json`
`X-Rach-Signature`	`sha256=<hex>` — HMAC-SHA256 of the raw request body, keyed with the webhook’s secret (returned when the webhook is registered)
`User-Agent`	`Rach-CaaS-Webhooks/1.0`

Signature verification (Node)

const crypto = require('crypto');
const expected = 'sha256=' + crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)                 // exact bytes received, before JSON.parse
  .digest('hex');
const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.header('X-Rach-Signature')),
);

Conventions

Delivery is best-effort — settlement already happened on-chain; the notification never blocks it. Only webhooks subscribed to that event type receive it. Return 2xx.
Amounts are decimal strings with 6 dp (e.g. "5.000000").
tx_hash is the real on-chain transaction identifier, never an internal operation ID. EVM events use an EVM hash; native TRON USDT and Solana SPL events also include the same native identifier in tx_id (network: "mainnet" for TRON and network: "mainnet-beta" for Solana).
Timestamps are RFC3339 UTC.
On *.settled / *.failed, empty fields are omitted, not null (reason absent on success; amount_*/token/tx_hash absent on a pre-broadcast failure). Treat missing = unknown.

Transaction events

transfer.received
transfer.settled
transfer.failed
swap.settled
swap.failed

Fires when a wallet belonging to your business receives funds (incl. cross-merchant). Not sent if the recipient is an unaffiliated phone — they get an SMS instead. Delivered to the recipient merchant.

{
  "event": "transfer.received",
  "transfer_id": "rach_txn_9f2c…",
  "recipient_wallet": "0xFDd4ABaF518d49A6749A3aD6A68f9403bD93cFF0",
  "amount_usdc": "288.000000",
  "token": "USDC",
  "tx_hash": "0xec586fed…",
  "settled_at": "2026-08-14T08:41:12Z"
}

For a confirmed native TRON USDT deposit, the same event is emitted after a solidified TRC-20 Transfer log. Deduplicate on transfer_id; it is the durable deposit ID, not merely the transaction hash. amount_usdc remains only for compatibility with older consumers — use amount together with token: "USDT" as the authoritative amount and asset.

{
  "event": "transfer.received",
  "transfer_id": "b5ecb7ac-…",
  "recipient_wallet": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "amount_usdc": "25.000000",
  "amount": "25.000000",
  "token": "USDT",
  "tx_hash": "a9e3…",
  "tx_id": "a9e3…",
  "network": "mainnet",
  "settled_at": "2026-08-28T10:00:00Z"
}

For a finalized Solana USDC or USDT deposit, the same durable receipt event is emitted after the scanner stores the balance delta. This requires Solana receipt monitoring to be enabled for your Rach environment; readiness confirms that configuration, not scanner-worker progress or a specific delivery. It is also delivered to every current wallet member. Deduplicate on transfer_id: the Solana signature is an audit reference, but one chain transaction can contain more than one credit.

{
  "event": "transfer.received",
  "transfer_id": "b5ecb7ac-…",
  "recipient_wallet": "7EqQdEULxWcraVx3mXKFjc84LhCkMGZCkRuDpvcMwJeK",
  "amount_usdc": "25.000000",
  "amount": "25.000000",
  "token": "USDT",
  "tx_hash": "5tJx…",
  "tx_id": "5tJx…",
  "network": "mainnet-beta",
  "settled_at": "2026-09-03T12:00:00Z"
}

Your outbound transfer confirmed on-chain. Delivered to the initiating merchant.

{
  "event": "transfer.settled",
  "transfer_id": "rach_txn_9f2c…",
  "status": "SETTLED",
  "amount_usdc": "288.000000",
  "token": "USDC",
  "tx_hash": "0xec586fed…",
  "updated_at": "2026-08-14T08:41:12Z"
}

{
  "event": "transfer.failed",
  "transfer_id": "rach_txn_9f2c…",
  "status": "FAILED",
  "reason": "blockchain execution reverted on-chain (bundler receipt failed)",
  "updated_at": "2026-08-14T08:41:12Z"
}

{
  "event": "swap.settled",
  "swap_id": "rach_swap_e44fc5b8…",
  "status": "SETTLED",
  "token_in": "USDT",
  "token_out": "USDC",
  "amount_in": "5.000000",
  "tx_hash": "0x78da1625…",
  "updated_at": "2026-08-14T08:41:12Z"
}

swap.settled.amount_out is not yet populated (it requires parsing the tokenOut Transfer log). Use amount_in, tx_hash and the on-chain tx for reconciliation meanwhile.

{
  "event": "swap.failed",
  "swap_id": "rach_swap_e44fc5b8…",
  "status": "FAILED",
  "token_in": "USDT",
  "token_out": "USDC",
  "amount_in": "5.000000",
  "reason": "swap reverted on-chain",
  "updated_at": "2026-08-14T08:41:12Z"
}

Account / membership events

{
  "event": "user.linked",
  "wallet_address": "0x…",
  "new_merchant_id": "uuid",
  "linked_at": "2026-08-14T08:41:12Z"
}

{
  "event": "user.phone_changed",
  "wallet_address": "0x…",
  "changed_by_merchant_id": "uuid",
  "changed_at": "2026-08-14T08:41:12Z"
}

Field-name notetransfer.received uses settled_at; the status events (*.settled / *.failed) use updated_at. Both are RFC3339 UTC. If a webhook is missed, poll GET /v1/swaps/:id (or the equivalent transfer endpoint) — it returns the same status fields.

Review delivery logs in your CaaS dashboard.

Best practices

Verify against the raw bodyCompute the HMAC over the exact bytes received. Re-serializing parsed JSON changes the bytes and breaks the signature.

Respond fast (2xx) then work async — Rach retries non-2xx deliveries.
Be idempotent — dedupe on X-Webhook-ID (Payments, or deposit_id for deposits).
Credit only when safe — for deposits, wait for safe_to_credit: true.

Get Started

Core Products

Monitoring & Webhooks

Payments webhooks

Configure your endpoint

Headers on every delivery

Events & exact payloads

Deposit `data` — field reference

Verify the signature

Test it

CaaS webhooks

Delivery & verification (every event)

Transaction events

Account / membership events

Best practices

​Payments webhooks

​Configure your endpoint

​Headers on every delivery

​Events & exact payloads

​Deposit data — field reference

​Verify the signature

​Test it

​CaaS webhooks

​Delivery & verification (every event)

​Transaction events

​Account / membership events

​Best practices

Payments webhooks

Configure your endpoint

Headers on every delivery

Events & exact payloads

Deposit `data` — field reference

Verify the signature

Test it

CaaS webhooks

Delivery & verification (every event)

Transaction events

Account / membership events

Best practices