Add a reCAPTCHA v2 widget to a protected page and verify its response through Darwinium. The Marketplace package separates the browser presentation from server-side verification, allowing you to add the browser pieces through a CDN-proxied HTML response.
The supplied verification template uses Google's v2 Siteverify endpoint and a legacy v2 secret key. It is not a reCAPTCHA Enterprise assessment integration.
Understand the two steps
The package uses an HTML page step and a token callback step:
- The page receives the widget placement and JavaScript injections.
- After the visitor completes the challenge, the injected script POSTs a token to
/recaptcha/response_token. - A matching journey step maps that token and calls Siteverify.
- Your workflow associates the verified result with the protected action.
Installing the package creates neither the callback step nor a policy for the eventual login or payment. Configure those explicitly.
1. Add the widget to the HTML response
Install Google Recaptcha, import recaptcha.snippet and add Place Google reCaptcha v2 Window (inject_recaptcha_v2_placement) to the page's HTML response mapping. Choose the HTML target before which the widget container should appear, such as the relevant form.
Add Inject Google reCaptcha v2 JS Code (inject_recaptcha_v2_code) to /html/head or /html/body. Configure:
| Setting | Value |
|---|---|
| Recapcha v2 Key | The public site key for your registered hostname |
| Theme | light or dark |
| Before Validation JS | Optional browser code to change the page before completion |
| Validation Passed JS | Optional browser code after the browser challenge callback |
The last two settings are JavaScript, despite their internal argument names ending in selector. Leave them empty unless you need a page interaction. The browser callback fires before server-side verification, so use it for presentation rather than authorization. Ensure the page's Content Security Policy permits the Google scripts and required resources.
2. Create and map the callback step
Create a step matching POST /recaptcha/response_token on the same host. The injected code sends multipart form data containing response_token plus two marker fields. In the step's request multipart mappings, map response_token to:
custom.general_purpose['recaptcha_response_token']
Configure how this callback endpoint returns a response in your deployment. It must have an intentional handler rather than accidentally reaching an unrelated application route.
3. Verify the token
Add Call Google reCaptcha v2 SiteVerify API (site_verify_recaptcha_v2) to the callback step under Workflows → Models. Set Legacy Recapcha v2 Secret Key to {{ secret(recaptcha_v2_secret) }} after mapping that secret.
Depend on LOCAL.REQUEST so the token mapping is available. The operation submits secret and response as form fields to Google's Siteverify endpoint.
| Output attribute | Value |
|---|---|
integrations.fraud['recapcha2_success'] |
Verification success |
integrations.fraud['recapcha2_hostname'] |
Challenge hostname |
integrations.fraud['recapcha2_challenge_ts'] |
Challenge timestamp |
integrations.fraud['recapcha2_error-code'] |
First error code |
integrations.fraud['recapcha2_error-code2'], ['recapcha2_error-code3'] |
Further errors |
The recapcha2 spelling is part of the supplied attribute keys; use it exactly.
4. Connect verification to the protected action
For a decision on the callback event, depend on the verification operation and check success plus the expected hostname. If the protected submission occurs on another event, deliberately correlate it with this verified challenge using your journey/session design. A successful callback must not automatically authorize unrelated later submissions.
Another design is to submit the token with the protected form and verify it on that submission step. That requires adapting the browser callback and mapping the new token source. See Map, inject & extract data and Dependencies & execution order.
Test the whole sequence
Check the rendered widget, the callback request, its mapped token, the Siteverify fields and the eventual protected action. Repeat with a missing, expired and reused token. Google's verification tokens expire after two minutes and can be verified once; see Verify the user's response.