Webhooks

Register a webhook

The URL must be HTTPS and must resolve to a publicly routable address. Loopback, private, link-local and otherwise reserved addresses are rejected at registration with 422 WEBHOOK_URL_FORBIDDEN, and re-checked immediately before every delivery — so a hostname that later starts resolving to an internal address stops being delivered to. Webhooks are environment-scoped: one registered with a test key never receives live events, and vice versa. Registration is limited to 5 per hour.

{
  "url": "https://your-app.example.com/rsends/webhook",
  "events": ["payment.completed", "payment.expired"]
}

{
  "webhook_id": 42,
  "url": "https://your-app.example.com/rsends/webhook",
  "secret": "a1b2c3…   (64 hex chars)",
  "events": ["payment.completed", "payment.expired"],
  "is_active": true
}

Send a test delivery

Posts a sample event to your URL so you can confirm your endpoint and signature check work before a real payment.

The settlement event

When a payment settles on-chain and RSends matches it to your intent, you receive payment.completed. This is the one event you should treat as “money received.” payment.expired fires when an intent lapses unpaid. In the rare case of a deep chain reorganization shortly after completion, payment.reversed can follow a payment.completed within roughly the chain’s finality window (~15 minutes on Base) — treat it as “stop fulfilment.” After a payment.reversed, poll the intent before writing the order off: if the network re-includes the transaction, the intent returns to paid without a second payment.completed.

Event payload

Deliveries POST a JSON body. Every event carries the same field set — the example below is the full shape, and the test delivery posts exactly it. Alongside the intent fields, it carries the on-chain proof of settlement — the transaction hash, the chain (canonical lowercase name plus numeric chain_id), and the onchain_invoice_id you can look up directly. Amount fields are strings, and amount is what settled to you — whole, never net of anything. There is deliberately no fee field: RSends is paid by off-chain subscription, and where the deployed router charges the payer an on-chain fee it is readable from the transaction itself via tx_hash.

{
  "event_id": "evt_3f9a…",
  "event": "payment.completed",
  "intent_id": "pi_abc123…",
  "reference_id": "a1b2c3d4e5f6a7b8",
  "onchain_invoice_id": "0x9f…",        // on-chain key for the PaymentMade event
  "amount": "100",
  "amount_received": "100",
  "overpaid_amount": null,
  "underpaid_amount": null,
  "currency": "USDC",
  "chain": "base_sepolia",
  "chain_id": 84532,
  "recipient": "0x…",                    // where the funds settled
  "tx_hash": "0x…",                      // the settlement transaction
  "status": "completed",
  "completed_late": false,
  "late_minutes": null,
  "metadata": { "order_id": "ORD-1024" },
  "timestamp": "2026-06-30T12:00:05+00:00",
  "created_at": "2026-06-30T12:00:00+00:00",
  "completed_at": "2026-06-30T12:00:05+00:00",
  "settlement": "onchain"                // extra on settlement events only
}

Delivery headers & signature

The signature covers both the timestamp and the exact raw body, so tampering with either invalidates it. This is the only signing scheme RSends uses — there is no other variant to support.

import crypto from 'node:crypto'

function verifyRSendsWebhook(secret, headers, rawBody) {
  const ts  = headers['x-rsend-timestamp']
  const sig = headers['x-rsend-signature']

  // 1) Freshness: reject anything outside a 5-minute window (anti-replay).
  const now = Math.floor(Date.now() / 1000)
  if (!ts || Math.abs(now - Number(ts)) > 300) return false

  // 2) Recompute HMAC-SHA256 over "{timestamp}.{rawBody}" and compare in
  //    constant time. rawBody MUST be the exact bytes received (do not re-serialize).
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex')

  return sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
}

Retries

A delivery counts as accepted when your endpoint answers 2xx. Anything else — a non-2xx status, a timeout, a connection error — is retried. Each attempt has a 10-second timeout, and there are up to 5 retries with exponential backoff:

After the 5th retry the delivery is marked failed and is not attempted again — reconcile from Reporting or the chain. Answer quickly and do the work asynchronously: a slow handler that exceeds 10 seconds is treated as a failure even if it eventually succeeds, which turns into duplicate deliveries.

Refund events are merchant-recorded

RSends never moves money, so there is no processor-driven refund event. A refund is a transfer you send from your own wallet and then record against the original payment for reporting — see Refunds.

Verify on-chain yourself