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.
- Build an HTTPS endpoint, for example
https://shop.example.com/webhooks/rocketramp. - Register it with the same headers as the Prefill API:
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_..." } }- The
signing_secretis returned once. Store it encrypted next to your API Key. - New secret:
POST https://api.coinsub.io/v1/merchants/YOUR_MERCHANT_ID/webhooks/WEBHOOK_ID/rotate-secret. Update your server in the same minute. - List:
GET .../webhooks. Turn one off:POST .../webhooks/WEBHOOK_ID/disable. - For a sub-merchant account, register the webhook with that account's own API Key and Merchant ID. The parent account's key is refused with 403.
- If deliveries stop, register a new webhook and disable the old one. RocketRamp can switch off delivery on its side, and the API still reports the webhook as active.
- If you change servers or domains, register the new URL the same day. Payments made in between complete, but your server never hears about them.
Request headers
| Header | Meaning |
|---|---|
X-Webhook-Timestamp | Unix time (seconds) when the webhook was signed |
X-Webhook-Signature | The signature (base64) |
X-Webhook-Signature-Version | v1 |
X-Event-Id | Unique ID of this event, the same on every retry |
Payload
{
"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
| Field | Meaning |
|---|---|
type | embed_transfer for every checkout payment. |
status | success means the money moved. Credit only on success. |
merchant_id | Your Merchant ID with a mrch_ prefix. Strip the prefix and compare it with your own ID. |
amount | The amount actually paid, as a string with up to 6 decimals. Parse as a decimal, never a float. Credit this amount. |
transfer_id | Unique per transfer. Store it with a UNIQUE constraint to stop double credits. |
embed_code | The checkout this payment came from. Look up your saved row to find the customer. |
destination_email | The recipient email you sent in the prefill. |
sender_email | The payer's RocketRamp email. |
memo | The memo you sent in the prefill. |
timestamp | When the transfer completed (ISO 8601). |
Your prefill metadata is not in the payload. Match on embed_code.
Verify the signature
signature = base64( HMAC_SHA256( signing_secret, X-Webhook-Timestamp + "." + raw_body ) )- Sign the timestamp, a dot, then the body. The body alone does not match.
- Use the raw body bytes exactly as received, before JSON parsing. Parsing and re-encoding changes the bytes.
- Encode in base64, not hex, and compare in constant time.
- Reject a timestamp more than 300 seconds from your clock.
- Refuse everything if the secret is missing. "No secret configured" never means "skip the check".
- Touch nothing before verification passes: no database writes, no parsing, no logging of the body.
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);
});$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);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
- Find the saved checkout by
embed_code. No match: do not credit; alert a person (real money with no customer). - 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. - A duplicate
transfer_idmeans this transfer is already credited: roll back and reply 200. - 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.
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 200Also 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.
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.