synctera-webhooks

Synctera Webhooks

When to Use This Skill

• How do I receive Synctera webhooks?
• How do I verify Synctera webhook signatures (Synctera-Signature)?
• How do I handle ACCOUNT.UPDATED or TRANSACTIONS.POSTED.CREATED events?
• Why is my Synctera webhook signature verification failing?
• How do I generate a Synctera webhook signing secret?

Verification (core)

Synctera uses a custom HMAC scheme (not Standard Webhooks). Each delivery has two headers:

• Synctera-Signature — the hex-encoded signature (two .-delimited signatures during secret rotation)
• Request-Timestamp — POSIX seconds used in the signed string

The signed string is `${Request-Timestamp}.${raw_body}` (the . is a literal separator). Compute HMAC-SHA256(secret, signed_string) and hex-encode. The secret is not your API key — generate it with POST /v0/webhook_secrets (empty body) and store it. Verify against the raw body; don't JSON.parse first.

const crypto = require('crypto');

// secret comes from POST /v0/webhook_secrets (NOT your API key)
function verifySynctera(rawBody, signatureHeader, timestamp, secret, toleranceSec = 300) {
  if (!signatureHeader || !/^\d+$/.test(String(timestamp))) return false;

  // Replay protection: Request-Timestamp must be within 5 minutes of now
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > toleranceSec) return false;

  // HMAC over `${timestamp}.${rawBody}` — the "." is a literal separator
  const expected = crypto.createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`).digest('hex');

  // During a rolling secret, the header holds two "."-delimited signatures
  return signatureHeader.split('.').some((sig) => {
    try { return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)); }
    catch { return false; }
  });
}

For complete handlers with route wiring, event dispatch, and tests, see:

• examples/express/
• examples/nextjs/
• examples/fastapi/