bridge-api-webhooks

Bridge API Webhooks

Which Bridge? This skill is for Bridge API (bridgeapi.io), the open-banking / account-aggregation platform by Bridge (formerly Bankin'). It is not bridge.xyz (the stablecoin/crypto payments company). See bridge-xyz-webhooks for that one.

When to Use This Skill

• How do I receive Bridge API webhooks?
• How do I verify the BridgeApi-Signature header?
• Why is my Bridge API webhook signature verification failing?
• How do I handle item.refreshed, item.account.updated, or payment.transaction.created events?
• How do I support Bridge's signing-secret rotation (two active secrets)?

Verification (core)

Bridge signs the raw request body with HMAC-SHA256, keyed on the webhook's signing secret, and sends the digest in the BridgeApi-Signature header as one or more scheme-prefixed, comma-separated values — hex, uppercase:

BridgeApi-Signature: v1=E5637CDB...,v1=A1B2C3D4...

Only the v1 scheme is valid — ignore any other scheme to avoid downgrade attacks. Multiple v1 values can appear during a secret rotation (the old secret stays valid for 24h, up to 2 active signatures), so accept the webhook if any v1 value matches. Compare timing-safe over the raw body.

Node:

const crypto = require('crypto');

function verifyBridgeWebhook(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  // Keep only v1= signatures (ignore other schemes → no downgrade), strip the prefix
  const signatures = signatureHeader.split(',')
    .map((s) => s.trim())
    .filter((s) => s.startsWith('v1='))
    .map((s) => s.slice(3));
  if (signatures.length === 0) return false;
  // hex decode is case-insensitive, so Bridge's UPPERCASE hex compares cleanly
  return signatures.some((sig) => {
    try {
      return crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
    } catch {
      return false; // malformed / length mismatch
    }
  });
}