configcat-webhooks

ConfigCat Webhooks

When to Use This Skill

• How do I receive ConfigCat webhooks?
• How do I verify the ConfigCat X-ConfigCat-Webhook-Signature-V1 header?
• Why is my ConfigCat webhook signature verification failing?
• How do I react when a feature flag or setting changes in ConfigCat?
• Why does my ConfigCat webhook fail with two signing keys, or when it uses GET?

Verification (core)

ConfigCat sends X-ConfigCat-Webhook-ID, X-ConfigCat-Webhook-Timestamp (Unix seconds) and X-ConfigCat-Webhook-Signature-V1. The signature is the standard base64 (padded) HMAC-SHA256 of the webhook ID, the timestamp and the raw body, concatenated with no separators. The key is the whole signing key (configcat_whsk_...) as UTF-8 bytes, not decoded. The body may be empty (GET), then only ID + timestamp are signed.

const crypto = require('crypto');

function verify(rawBody, id, timestamp, signature, secret) {
  if (!id || !timestamp || !/^[A-Za-z0-9+\/]{43}=$/.test(signature || '')) return false;
  const message = Buffer.concat([Buffer.from(id, 'latin1'), Buffer.from(timestamp, 'latin1'), rawBody]);
  const expected = Buffer.from(crypto.createHmac('sha256', Buffer.from(secret, 'utf8')).update(message).digest('base64'));
  const received = Buffer.from(signature);
  return expected.length === received.length && crypto.timingSafeEqual(expected, received);
}

import base64, hashlib, hmac, re

def verify(raw_body: bytes, wid: str, ts: str, signature: str, secret: str) -> bool:
    if not wid or not ts or not re.fullmatch(r"[A-Za-z0-9+/]{43}=", signature or ""):
        return False
    message = wid.encode("latin-1") + ts.encode("latin-1") + raw_body
    digest = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).digest()
    return hmac.compare_digest(base64.b64encode(digest), signature.encode("ascii"))  # compare the base64 text

Verify the raw bytes before parsing (never JSON.parse then re-serialise). Missing headers, a malformed value or a mismatch is a 401. The documented vector (secret configcat_whsk_VN3juirnVh5pNvCKd81RYRYchxUX4j3NykbZG2fAy88=, body examplebody, ID b616ca659d154a5fb907dd8475792eeb, timestamp 1669629035) must produce Ks3cYsu9Lslfo+hVxNC3oQWnsF9e5d73TI5t94D9DRA=.