bridge-xyz-webhooks

Bridge (bridge.xyz) Webhooks

Bridge is a stablecoin orchestration platform (customers, KYC links, transfers, virtual accounts, cards). It delivers webhooks signed with an RSA-SHA256 signature and verified against a per-endpoint PEM public key returned when you create/update the webhook — there is no HMAC shared secret and no official SDK.

When to Use This Skill

• How do I receive Bridge webhooks?
• How do I verify the Bridge X-Webhook-Signature header?
• Why is my Bridge webhook signature verification failing?
• How do I handle customer.updated, kyc_link.updated, transfer.updated, or virtual_account.activity events?
• How do I create and enable a Bridge webhook endpoint via the API?

Verification (core)

Bridge sends X-Webhook-Signature: t=<timestamp_ms>,v0=<base64_signature>. Verify with the endpoint's RSA public key (the public_key PEM from the webhook API response). Use the raw request body — don't JSON.parse first.

Quirk: Bridge SHA256-hashes <timestamp>.<rawBody> to a digest, then RSA-SHA256 verifies that digest — so the digest is hashed again inside verify. Feed the digest (not the raw string) into an RSA-SHA256 verifier, exactly as below.

const crypto = require('crypto');

function verifyBridgeSignature(rawBody, header, publicKeyPem, toleranceMs = 10 * 60 * 1000) {
  const parts = {};                                  // split on FIRST '=' — base64 '=' padding is safe
  for (const p of header.split(',')) {
    const i = p.indexOf('=');
    parts[p.slice(0, i)] = p.slice(i + 1);
  }
  const { t: timestamp, v0: signature } = parts;
  if (!timestamp || !signature) return false;
  if (Date.now() - Number(timestamp) > toleranceMs) return false;   // reject stale events (replay guard)

  const digest = crypto.createHash('sha256').update(`${timestamp}.${rawBody}`).digest();
  const verifier = crypto.createVerify('sha256');    // RSA-SHA256 hashes `digest` a second time
  verifier.update(digest);
  verifier.end();
  try {
    return verifier.verify(publicKeyPem, signature, 'base64');
  } catch {
    return false;
  }
}