circle-webhooks

Circle Webhooks

When to Use This Skill

• How do I receive Circle webhooks?
• How do I verify Circle webhook signatures (ECDSA / X-Circle-Signature)?
• How do I fetch and cache the Circle notification public key by X-Circle-Key-Id?
• How do I handle cpn.payment.*, cpn.transaction.*, or cpn.rfi.* notifications?
• Why is my Circle webhook signature verification failing?

How Circle Webhooks Differ From Most Providers

Circle's v2 notifications are signed with an asymmetric ECDSA key — not HMAC, and not the Standard Webhooks spec. Each POST carries two headers:

You verify by fetching the matching public key from Circle's API (GET /v2/cpn/notifications/publicKey/{keyId}, returns a base64 DER/SPKI key), then verifying the signature over the raw request body with ECDSA-SHA256. The public key for a keyId is static — cache it by keyId to avoid an API call per event.

Two more Circle specifics:

• HEAD validation. On subscription create/update Circle validates your endpoint with a HEAD request (no subscribe-URL handshake). Return 200 to HEAD as well as POST.
• Product scope. This skill covers Circle Payments Network (CPN) v2 notifications, which use a notificationType body field carrying cpn.* event strings (cpn.payment.completed, cpn.transaction.broadcasted, cpn.rfi.approved, …). Circle Mint / Core API (v1) is a separate product with a different notification scheme — this skill does not cover it.

Verification (core)

Circle has no webhook-verify SDK helper, so verify manually. Node.js:

const { createPublicKey, createVerify } = require('crypto');
const publicKeyCache = new Map(); // keyId -> KeyObject (public keys are static)

async function getPublicKey(keyId) {
  if (publicKeyCache.has(keyId)) return publicKeyCache.get(keyId);
  const res = await fetch(
    `${process.env.CIRCLE_API_BASE_URL}/v2/cpn/notifications/publicKey/${keyId}`,
    { headers: { Authorization: `Bearer ${process.env.CIRCLE_API_KEY}` } }
  );
  const { data } = await res.json();
  const key = createPublicKey({
    key: Buffer.from(data.publicKey, 'base64'), // base64 DER (SPKI)
    format: 'der',
    type: 'spki',
  });
  publicKeyCache.set(keyId, key);
  return key;
}

async function verifyCircleWebhook(headers, rawBody) {
  const signature = headers['x-circle-signature'];
  const keyId = headers['x-circle-key-id'];
  if (!signature || !keyId) return false;
  const publicKey = await getPublicKey(keyId).catch(() => null);
  if (!publicKey) return false;
  const verifier = createVerify('SHA256');
  verifier.update(rawBody); // raw bytes, not parsed JSON
  verifier.end();
  try {
    return verifier.verify(publicKey, signature, 'base64');
  } catch {
    return false;
  }
}