CAPTCHA: detection and solving

CAPTCHAs happen. No matter how good your IP and browser fingerprint, there is no browsing without CAPTCHAs these days. Even on home computers with crystal clear IPs.

Rebrowser recognizes the most common antibot systems and checks your active pages for CAPTCHAs in the background. The check only reads the page from an isolated context, so the website's own scripts can't see it.

Once a CAPTCHA is detected, we send a CDP event Rebrowser.captchaDetected. If automatic solving is enabled and the CAPTCHA is one we solve (Cloudflare), Rebrowser solves it and then sends Rebrowser.captchaSolved with the final status. Solving usually takes a few seconds, but some Cloudflare pages need two rounds and can take up to 40 seconds.

Supported CAPTCHAs

Events

Rebrowser.captchaDetected is sent once per CAPTCHA:

• captchaId: ID of the detected CAPTCHA.
• vendor: cloudflare, recaptcha, hcaptcha or datadome.
• kind: what is on the page. challengePage (Cloudflare full-page check), checkbox (a box to tick), challenge (an image or slider puzzle is open), blocked (DataDome hard block, it can't be passed even manually) or interstitial (DataDome device check that didn't clear within 15 seconds).
• sitekey: the site key, when the vendor exposes one (reCAPTCHA, hCaptcha).
• willSolve: true when Rebrowser is going to solve it automatically.

Rebrowser.captchaSolved is sent when automatic solving is enabled:

• captchaId: the same ID as in Rebrowser.captchaDetected.
• status: success when the CAPTCHA was passed. notSupported right after detection for CAPTCHAs we don't solve automatically, so your script doesn't wait for nothing. Other values (fail, expired, timeout, noCheckbox, notClickable, navigatedAway, failed) mean the CAPTCHA was not passed.

How to listen for CDP events?

It's very easy to listen for a custom CDP event from Rebrowser. Take a look below at example code for Puppeteer and Playwright libraries.

1
2
3
4
5
6
7
8
// puppeteer
page._client().on('Rebrowser.captchaDetected', (params) => console.log('[captchaDetected]', params))
page._client().on('Rebrowser.captchaSolved', (params) => console.log('[captchaSolved]', params))

// playwright
const cdp = await page.context().newCDPSession(page)
cdp.on('Rebrowser.captchaDetected', (params) => console.log('[captchaDetected]', params))
cdp.on('Rebrowser.captchaSolved', (params) => console.log('[captchaSolved]', params))

You can also wait for these events after the page is loaded:

1
2
3
4
5
6
// puppeteer
await new Promise((resolve) => page._client().on('Rebrowser.captchaDetected', resolve))

// playwright
const cdp = await page.context().newCDPSession(page)
await new Promise((resolve) => cdp.on('Rebrowser.captchaDetected', resolve))

Cloudflare

Cloudflare CAPTCHA is getting more and more popular as it comes as a default, free, and convenient option when a website is served by Cloudflare.

✅ Rebrowser detects and solves it automatically, both the full-page "Just a moment..." check and Turnstile widgets inside forms. Some websites ask for the checkbox twice in a row; Rebrowser handles that too.

☝️ If the page keeps showing "Verifying..." and never shows a checkbox, Cloudflare doesn't trust the current IP or session. There is nothing to click in that case, try another proxy.

reCAPTCHA

This is one of the oldest and most popular CAPTCHA systems. It's developed by Google and used on many websites in different forms.

reCAPTCHA could be used as part of the form or it could be invisible, meaning that you will see it only when you do some action (for example, submitting a form) and your reCAPTCHA score is quite low.

✅ Rebrowser detects a visible reCAPTCHA checkbox or an open image challenge and reports it with its site key. Invisible and score-based (v3) reCAPTCHA have nothing to interact with, so they are not reported. Automatic solving is not available at the moment.

hCaptcha

It's quite similar to reCaptcha, using almost the same API as their initial goal was to make it as easy as possible to migrate from reCaptcha to hCaptcha.

✅ Rebrowser detects a visible hCaptcha checkbox or an open challenge and reports it with its site key. Automatic solving is not available at the moment.

DataDome

✅ Rebrowser detects the DataDome slider puzzle (kind: challenge) and the hard block page (kind: blocked). The device check page usually clears by itself, so it is reported only if it stays for more than 15 seconds. Automatic solving is not available at the moment.

DataDome is really sensitive to many things that your scripts could do. If you see their CAPTCHA, first of all, try to start your new Rebrowser session without any of your scripts involved.

No page.evaluate() or anything else. Just try to open your target website with the Rebrowser and see how it goes.

If you have a decent proxy with a non-flagged IP, most likely you won't see any DataDome CAPTCHA at all. If this is the case, then the CAPTCHA is triggered by some of your scripts.

If you get kind: blocked, it's your IP or your scripts. It's impossible to pass this page even manually (you can try it using our live view mode right from your dashboard). Focus on your scripts and your proxy; there is something that triggers it.

We highly suggest reading our blog posts about isolated and main contexts, and try to move your code as much as you can into isolated context minimizing chances to be detected. Also, make sure to pass all the tests on our bot detector page.

Also, there could be some really surprising side effects. For example, DataDome will be triggered with this simple code:

1
page.evaluate(() => document.querySelector('recaptcha'))

Yes, it's really that deep. But if you run the same code in an isolated context, it won't be able to catch it.

Imperva (Incapsula)

Imperva (also known as Incapsula) is an interstitial page that shows hCaptcha.

✅ Rebrowser detects the hCaptcha on Imperva pages and reports it as vendor: hcaptcha. Automatic solving is not available at the moment.

Settings

Detection and solving are controlled by the "CAPTCHA behavior" option in browser settings of a profile or a group:

• off: don't detect and don't solve CAPTCHAs (default).
• detect: detect CAPTCHAs and send Rebrowser.captchaDetected, but don't solve them.
• detectAndSolve: detect CAPTCHAs and solve the supported ones automatically.

Changes in browser settings are applied starting with the next run.

You can also choose the behavior for a single run with the captchaBehavior parameter when you start it. It overrides the browser settings for that run only:

1
2
3
4
5
6
7
const rebrowserParams = {
  apiKey: 'YOUR_API_KEY',
  captchaBehavior: 'detectAndSolve', // off | detect | detectAndSolve
}
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://ws.rebrowser.net/?${new URLSearchParams(rebrowserParams)}`,
})

The same parameter works with the startRun API.