Skip to main content

Google reCAPTCHA Validation

Validate webhook requests using Google reCAPTCHA v2 or v3 to prevent bot submissions.

{
    "recaptcha_v3_webhook": {
        "data_type": "json",
        "module": "log",
        "recaptcha": {
            "secret_key": "your_recaptcha_v3_secret_key",
            "version": "v3",
            "token_source": "header",
            "token_field": "X-Recaptcha-Token",
            "min_score": 0.5
        }
    }
}

reCAPTCHA v2​

{
    "recaptcha_v2_webhook": {
        "data_type": "json",
        "module": "log",
        "recaptcha": {
            "secret_key": "your_recaptcha_v2_secret_key",
            "version": "v2",
            "token_source": "body",
            "token_field": "g-recaptcha-response"
        }
    }
}

Configuration Options​

OptionTypeRequiredDefaultDescription
secret_keystringYes-Your reCAPTCHA secret key from Google
versionstringNo"v3"reCAPTCHA version: "v2" or "v3"
token_sourcestringNo"header"Token location: "header" or "body"
token_fieldstringNo"X-Recaptcha-Token"Field name to look for token
min_scorefloatNo0.5Minimum score for v3 validation (0.0-1.0)
Automatic Body Token Detection

When token_source is "body", the system automatically searches for the token in these fields (in order):

  1. The field specified in token_field
  2. recaptcha_token
  3. recaptcha
  4. g-recaptcha-response

This allows compatibility with various frontend implementations without explicit configuration.

Usage​

Send token in X-Recaptcha-Token header:

curl -X POST http://localhost:8000/webhook/recaptcha_v3_webhook \
  -H "X-Recaptcha-Token: <recaptcha_token>" \
  -H "Content-Type: application/json" \
  -d '{"event": "test"}'

Body-based tokens (v2)​

Include token in JSON body:

{
    "event": "test",
    "g-recaptcha-response": "<recaptcha_token>"
}

Combined with other validators​

{
    "secure_webhook_with_recaptcha": {
        "data_type": "json",
        "module": "save_to_disk",
        "authorization": "Bearer token_123",
        "recaptcha": {
            "secret_key": "your_recaptcha_secret_key",
            "version": "v3",
            "token_source": "header",
            "min_score": 0.7
        }
    }
}

Features​

  • reCAPTCHA v2 and v3 support
  • Header or body token sources
  • Score-based validation (v3)
  • Bot protection
  • Combined with other authentication methods