Developer Docs

Webhooks

The only place your system should credit money. Register, verify the signature, and credit exactly once.

Docs menuWebhooks
Quick Start Setup & Credentials Prefill API Opening the Checkout Phones & In-App Browsers Webhooks Paying Your Users Reconciliation Environments Common Mistakes Go-Live Checklist FAQ

When a transfer completes, RocketRamp sends a POST to your webhook URL. This is the only place your system should credit money.

Setting up the webhook

Register your webhook through the API. This returns the signing secret you need to verify every webhook. A webhook URL typed into the dashboard's Merchant Settings arrives without a signature, so do not use that field.

  1. Build an HTTPS endpoint, for example https://shop.example.com/webhooks/rocketramp.
  2. Register it with the same headers as the Prefill API:
HTTP
POST https://api.coinsub.io/v1/merchants/YOUR_MERCHANT_ID/webhooks
Merchant-ID: YOUR_MERCHANT_ID
API-Key: YOUR_API_KEY
Content-Type: application/json

{ "url": "https://shop.example.com/webhooks/rocketramp" }

200 OK
{ "data": { "webhook_id": "288", "signing_secret": "whsec_..." } }

Request headers

HeaderMeaning
X-Webhook-TimestampUnix time (seconds) when the webhook was signed
X-Webhook-SignatureThe signature (base64)
X-Webhook-Signature-Versionv1
X-Event-IdUnique ID of this event, the same on every retry

Payload

JSON
{
  "type":              "embed_transfer",
  "status":            "success",
  "merchant_id":       "mrch_YOUR_MERCHANT_ID",
  "amount":            "25.000000",
  "transfer_id":       "292",
  "embed_code":        "ca678360-5ae6-4f6b-be1d-8583c02447cb",
  "destination_email": "payments@your-business.example.com",
  "sender_email":      "payer@example.com",
  "memo":              "Deposit for order 1234",
  "partner_user_id":   "...",
  "timestamp":         "2026-11-02T18:04:22Z"
}

Field reference

FieldMeaning
typeembed_transfer for every checkout payment.
statussuccess means the money moved. Credit only on success.
merchant_idYour Merchant ID with a mrch_ prefix. Strip the prefix and compare it with your own ID.
amountThe amount actually paid, as a string with up to 6 decimals. Parse as a decimal, never a float. Credit this amount.
transfer_idUnique per transfer. Store it with a UNIQUE constraint to stop double credits.
embed_codeThe checkout this payment came from. Look up your saved row to find the customer.
destination_emailThe recipient email you sent in the prefill.
sender_emailThe payer's RocketRamp email.
memoThe memo you sent in the prefill.
timestampWhen the transfer completed (ISO 8601).

Your prefill metadata is not in the payload. Match on embed_code.

Verify the signature

Signature
signature = base64( HMAC_SHA256( signing_secret, X-Webhook-Timestamp + "." + raw_body ) )
Node.js (Express)
const crypto = require('crypto');
app.post('/webhooks/rocketramp', express.raw({ type: '*/*' }), async (req, res) => {
  const ts  = req.get('X-Webhook-Timestamp') || '';
  const sig = req.get('X-Webhook-Signature') || '';
  const secret = process.env.ROCKETRAMP_WEBHOOK_SECRET || '';
  const expected = crypto.createHmac('sha256', secret).update(ts + '.').update(req.body).digest('base64');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
  if (!secret || !sig || !fresh || sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const ev = JSON.parse(req.body.toString('utf8'));
  if (String(ev.merchant_id).replace(/^mrch_/, '') !== process.env.ROCKETRAMP_MERCHANT_ID) return res.sendStatus(403);
  if (ev.type !== 'embed_transfer' || ev.status !== 'success') return res.sendStatus(200);   // record, do not credit
  await creditOnce(ev);              // see "Credit exactly once"
  res.sendStatus(200);
});
PHP
$raw    = file_get_contents('php://input');
$ts     = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$sig    = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$secret = getenv('ROCKETRAMP_WEBHOOK_SECRET') ?: '';
$ok = $secret !== '' && $ts !== '' && $sig !== '' && abs(time() - (int)$ts) <= 300
   && hash_equals(base64_encode(hash_hmac('sha256', $ts . '.' . $raw, $secret, true)), $sig);
if (!$ok) { http_response_code(401); exit; }
$ev = json_decode($raw, true);
if (preg_replace('/^mrch_/', '', (string)($ev['merchant_id'] ?? '')) !== getenv('ROCKETRAMP_MERCHANT_ID')) {
    http_response_code(403); exit;
}
if (($ev['type'] ?? '') !== 'embed_transfer' || ($ev['status'] ?? '') !== 'success') { http_response_code(200); exit; }
credit_once($db, $ev);
http_response_code(200);
Python
import base64, hashlib, hmac, os, time

def verify(raw_body: bytes, ts: str, sig: str) -> bool:
    secret = os.environ.get("ROCKETRAMP_WEBHOOK_SECRET", "")
    if not (secret and ts and sig) or abs(time.time() - int(ts)) > 300:
        return False
    mac = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).digest()
    return hmac.compare_digest(base64.b64encode(mac).decode(), sig)

Credit exactly once

  1. Find the saved checkout by embed_code. No match: do not credit; alert a person (real money with no customer).
  2. In one database transaction: insert the credit with its transfer_id (UNIQUE), add the amount to the customer's balance, and mark the checkout paid.
  3. A duplicate transfer_id means this transfer is already credited: roll back and reply 200.
  4. Reply 200 within a few seconds. Reply 5xx only when you could not record the event, for example the database is down; RocketRamp then retries.
SQL
BEGIN;
  SELECT customer_id FROM rr_checkouts WHERE embed_code = :embed_code FOR UPDATE;
  INSERT INTO rr_credits (transfer_id, embed_code, customer_id, amount)
       VALUES (:transfer_id, :embed_code, :customer_id, :amount);      -- UNIQUE (transfer_id)
  UPDATE wallets SET balance = balance + :amount WHERE customer_id = :customer_id;
  UPDATE rr_checkouts SET status = 'paid', transfer_id = :transfer_id WHERE embed_code = :embed_code;
COMMIT;
-- duplicate key on transfer_id  =>  ROLLBACK, reply 200

Also keep a unique record of X-Event-Id to drop exact replays early. It is not part of the signature, so transfer_id remains the real guard.

Retries

A webhook that does not get a 2xx reply is retried up to 5 times, every 5 to 10 minutes, with the same X-Event-Id and transfer_id.

?