Webhooks

Why this page matters Webhooks are the main signal that keeps your app in sync with RampHub. If you get this right, the rest of the trade lifecycle is much easier to trust.

​

Headers

​

Signing secret

• Store the secret in the receiver’s environment or secret manager.
• Never put it in a browser bundle or public config file.
• Copy it when the dashboard reveals it and keep it on the receiving server only.
• Verify x-ramphub-signature against the raw request body before you trust the payload.
• Keep using monitor-status as the fallback path when a webhook is delayed or missing.
• If you rotate the endpoint secret, update the receiving server immediately.

​

Events

​

Common stage labels

• Order placed
• Awaiting settlement
• Forwarded to provider
• Awaiting provider funding confirmation
• Awaiting customer payment
• Invoice created
• Settling with provider
• Ready for settlement
• Awaiting user payout
• Marked completed
• Marked failed

​

Sample payload

{
  "id": "evt_01hzyx8j3m4w9v0g8s2f6t",
  "type": "transaction.completed",
  "createdAt": "2026-04-20T12:00:00.000Z",
  "livemode": true,
  "data": {
    "transactionId": "RH-TX-AB12CD34",
    "status": "completed",
    "provider": "UseBread",
    "asset": "USDT",
    "chain": "base"
  }
}

​

Signature verification

const crypto = require("crypto");

function verifyRampHubWebhook(rawBody, signature, secret) {
  const computed = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature),
  );
}

​

Rule