Node.js

Verify hCaptcha tokens on your server using Node.js with built-in fetch. This works with the JavaScript widget, React, and Vue.

Configure keys

Set HCAPTCHA_SECRET and HCAPTCHA_SITEKEY in your server environment using your dashboard credentials. Never expose the secret in client code.

Verify a token

Read h-captcha-response from the submitted form. Call this function from your request handler before performing the protected action. Pass a client IP only when obtained from a trusted source; do not trust arbitrary forwarded headers.

export async function verifyHCaptcha(token: string, remoteip?: string): Promise<boolean> {
  const secret = process.env.HCAPTCHA_SECRET;
  const sitekey = process.env.HCAPTCHA_SITEKEY;
  if (!token || !secret || !sitekey) return false;

  try {
    const body = new URLSearchParams({ secret, sitekey, response: token });
    if (remoteip) body.set('remoteip', remoteip);

    const response = await fetch('https://api.hcaptcha.com/siteverify', {
      method: 'POST',
      body,
      signal: AbortSignal.timeout(10000),
    });
    if (!response.ok) return false;

    const result = await response.json();
    return result?.success === true;
  } catch {
    return false;
  }
}

URLSearchParams sets the form encoding and Content-Type. Reject the protected action when this function returns false, including when verification times out. Return a retry message to the user and obtain a fresh token before another attempt.

Test the handler

Use the matching test sitekey and secret. Confirm valid test tokens succeed, missing and invalid tokens fail, and network failures do not allow the protected action.

See the verification reference for response fields and error codes. A successful hCaptcha check does not replace login credentials or other authorization checks.