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.

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.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. Enveloped payload:

{
  "event": "wallet.deposit.detected",
  "data": {
    "deposit_id": 8842,
    "customer_id": "cust_001",
    "network": "ETH",
    "address": "0xAbC123...",
    "amount": "125.50",
    "currency": "USDT",
    "tx_hash": "pending_8842",
    "hash_pending": true,
    "confirmations": 0,
    "status": "detected",
    "detected_at": "2026-08-14T12:05:00Z",
    "detected_by": "poller",
    "safe_to_credit": false
  }
}

Dedupe on deposit_id (the stable idempotency key), not tx_hash — tx_hash starts as a pending_… placeholder and is upgraded to the real on-chain hash via a follow-up wallet.deposit.hash_resolved event. Do not credit the customer until safe_to_credit is true.

Sent once the deposit reaches the required confirmations. safe_to_credit is now true:

{
  "event": "wallet.deposit.confirmed",
  "data": {
    "customer_id": "cust_001",
    "network": "ETH",
    "address": "0xAbC123...",
    "amount": "125.50",
    "currency": "USDT",
    "tx_hash": "0x9f8e7d6c5b4a...",
    "confirmations": 12,
    "status": "confirmed",
    "detected_at": "2026-08-14T12:05:00Z",
    "confirmed_at": "2026-08-14T12:09:30Z",
    "safe_to_credit": true
  }
}

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
  }
}

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 EVM transaction hash (explorer-lookupable), not the internal userOpHash.
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"
}

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

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

​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

Verify the signature

Test it

CaaS webhooks

Delivery & verification (every event)

Transaction events

Account / membership events

Best practices