Skip to main content

Solve HCaptcha

Solves hCaptcha challenges and returns a response token. hCaptcha is a privacy-focused alternative to reCAPTCHA, commonly used on websites that prioritize user privacy.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Session - The session ID returned from the Create Session node.
  • Website URL - The full URL of the target page where the hCaptcha appears (e.g., https://example.com/register).
  • Website Key - The site key (also called "data-sitekey") found in the page source. Format: 00000000-0000-0000-0000-000000000000.

Options​

  • No Cache - Disable result caching for this task. Default is false. Set to true to force a fresh solve.

Output​

  • Token - The hCaptcha response token (h-captcha-response) to submit with your form or API request.

How It Works​

The Solve HCaptcha node solves hCaptcha challenges. When executed, it:

  1. Retrieves the session using the provided session ID
  2. Creates an hCaptcha solving task with the website URL and site key
  3. Sends the task to CapMonster Cloud for processing
  4. Waits for the challenge to be solved
  5. Returns the response token (h-captcha-response)

Requirements​

  • A valid CapMonster session (from Create Session node)
  • The full URL where the hCaptcha is displayed
  • The hCaptcha site key from the page source
  • Sufficient account balance
  • Active internet connection

Error Handling​

The node will fail in the following cases:

  • Missing or invalid session ID
  • Session not found
  • Empty or invalid website URL
  • Empty or invalid site key
  • Insufficient account balance
  • Network connectivity issues
  • Captcha solving timeout
  • Unsupported hCaptcha configuration
  • Service temporarily unavailable

Finding hCaptcha Parameters​

To find the required parameters, inspect the page source:

Website URL​

Use the full URL of the page where the captcha appears:

https://example.com/register

Site Key (data-sitekey)​

Look for the hCaptcha widget in the HTML:

<div class="h-captcha" data-sitekey="00000000-0000-0000-0000-000000000000"></div>

Or in JavaScript:

hcaptcha.render('container', {
    sitekey: '00000000-0000-0000-0000-000000000000'
});

You can also find it by inspecting the iframe:

<iframe src="https://hcaptcha.com/captcha/v1/...?sitekey=00000000-0000-0000-0000-000000000000">

Usage Notes​

  • hCaptcha solving typically takes 15-30 seconds
  • The response token is valid for approximately 2 minutes
  • Use the token immediately after receiving it
  • The No Cache option forces a fresh solve, useful for testing
  • hCaptcha tokens are single-use only
  • Token format is different from reCAPTCHA

Example: Solving hCaptcha on Registration Form​

Inputs:

  • Session: (from Create Session node)
  • Website URL: https://example.com/register
  • Website Key: 10000000-ffff-ffff-ffff-000000000001

Options:

  • No Cache: false

Output:

  • Token: "P0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwYXNza2V5IjoiZ..."

Example: Complete Flow​

Create Session (API Key)
  → Browser: Navigate to registration page
    → Browser: Fill form fields
      → Browser: Get Attribute (data-sitekey from h-captcha element)
        → Solve HCaptcha
          → Browser: Execute Script (set h-captcha-response)
            → Browser: Click submit button

Submitting the Token​

After receiving the token, you need to submit it with your form. Common methods:

Method 1: Hidden Form Field​

document.querySelector('textarea[name="h-captcha-response"]').value = token;

Method 2: Using hCaptcha API​

// The token is automatically set if you use hCaptcha's callback
window.hcaptchaCallback = function(token) {
    console.log('Token received:', token);
    // Submit form
};

Method 3: API Request​

{
  "email": "user@example.com",
  "password": "password123",
  "h-captcha-response": "token_here"
}

Method 4: Direct Form Submission​

// Set the token in the hidden textarea
document.querySelector('[name="h-captcha-response"]').innerHTML = token;
// Trigger form submission
document.querySelector('form').submit();

Best Practices​

  • Store the site key as a variable for reuse
  • Validate the token format before submission
  • Handle token expiration with retry logic
  • Add appropriate delays to mimic human behavior
  • Monitor solve times and implement timeouts
  • Test with No Cache enabled during development
  • Always verify the site key matches the website URL
  • Use error handling to catch solving failures

Common Issues and Solutions​

Issue: Invalid site key error

  • Solution: Verify the site key format (UUID format)
  • Solution: Check if the key changes on page refresh
  • Solution: Ensure you're extracting the key from the correct element
  • Solution: Look for multiple hCaptcha instances on the page

Issue: Token not accepted by website

  • Solution: Verify you're setting the h-captcha-response field correctly
  • Solution: Check if the token has expired (2-minute validity)
  • Solution: Ensure the website URL matches exactly (including protocol and subdomain)
  • Solution: Verify the form submission method

Issue: "Invalid domain" error

  • Solution: The Website URL must match the domain where hCaptcha is implemented
  • Solution: Include the full URL with protocol (https://)
  • Solution: Don't use localhost or IP addresses if the site key is for a production domain

Issue: Solving takes too long or times out

  • Solution: Check CapMonster Cloud service status
  • Solution: Verify your internet connection
  • Solution: Increase timeout values in your flow
  • Solution: Check if the hCaptcha difficulty level is very high

Issue: "Token validation failed" on submission

  • Solution: Make sure you submit the token immediately
  • Solution: Verify you're not modifying the token value
  • Solution: Check that you're submitting to the correct endpoint

When to Use No Cache​

Enable No Cache (true) when:

  • Testing your integration
  • The captcha appears on different pages
  • You need guaranteed unique tokens
  • Debugging token acceptance issues
  • Working with high-security implementations

Keep No Cache disabled (false) when:

  • Running production automations (faster and cheaper)
  • Solving similar captchas repeatedly
  • Optimizing for cost efficiency

Differences from reCAPTCHA​

  • Field Name: hCaptcha uses h-captcha-response instead of g-recaptcha-response
  • Privacy: hCaptcha doesn't track users across sites
  • Token Format: Different token structure
  • Solve Time: Generally similar to reCAPTCHA v2
  • Implementation: Simpler integration, fewer parameters

Cost Considerations​

  • hCaptcha solving costs are similar to reCAPTCHA v2
  • Check CapMonster Cloud pricing for current rates
  • Monitor your balance when solving multiple captchas
  • Consider caching (No Cache = false) for cost efficiency
  • Batch processing can reduce per-captcha cost

Advanced Tips​

  • hCaptcha difficulty can vary by user reputation
  • Some implementations use passive verification (no puzzle shown)
  • Accessibility mode may require different handling
  • Enterprise implementations may have additional security features
  • Token length and format can vary by configuration
  • Always test with actual website before production deployment