How do I verify a CaptchaKit webhook signature?

Events and payload

A Business account can add webhook endpoints and subscribe each one to `verification.passed`, `verification.failed` and `game.solved`. Every delivery is a POST with a JSON body and these fields: `type`, `siteKey`, `gameId`, `success`, `timestamp`, and `failReason` on failures.

The `failReason` values are the same error strings that `POST /api/verify` returns, such as `Invalid or expired token` and `Token already used`. The secret for an endpoint is shown once, when you create it, so store it in an environment variable.

The signature header

Each request carries `X-CaptchaKit-Signature: t=<unix-ms>,v1=<hex>`. The value of `t` is the send time in milliseconds. The value of `v1` is the lowercase hex HMAC-SHA256 of the text `<t>.<body>`, keyed with the endpoint secret. The body in that text is the exact request body as sent.

Verify in Node

This function mirrors the signing code. The five minute tolerance is our suggestion, not a value the service enforces, so tune it to your clock drift.

Express parses JSON by default, which changes the bytes. Use `express.raw` on the webhook route so you hold the exact body, then parse it yourself after the check passes.

import crypto from 'node:crypto';

export function verifyCaptchaKitSignature(rawBody, header, secret, toleranceMs = 5 * 60 * 1000) {
  const parts = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  if (!parts.t || !parts.v1) return false;
  if (Math.abs(Date.now() - Number(parts.t)) > toleranceMs) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import express from 'express';

const app = express();

app.post('/captchakit-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const header = req.get('X-CaptchaKit-Signature') ?? '';
  if (!verifyCaptchaKitSignature(rawBody, header, process.env.CAPTCHAKIT_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(rawBody);
  // event.type, event.siteKey, event.gameId, event.success, event.timestamp
  res.sendStatus(200);
});

Delivery and auto-disable

Respond with a 2xx status quickly. A delivery has a 5 second timeout, and any non-2xx response or timeout counts as a failure. After 20 consecutive failures the endpoint is disabled automatically, and a successful delivery resets the count. Each event is sent once, so make your handler idempotent and log what you receive.

Questions

Sources

1. CaptchaKit documentation (checked 2026-10-18)
2. Node.js crypto documentation (checked 2026-10-18)
3. Node.js crypto.createHmac (checked 2026-10-18)

Related

• How to verify a CAPTCHA token on your server
• Verify a CAPTCHA token in Node.js
• CAPTCHA token expired or already used
• Are game CAPTCHAs secure? What they do and don't do