logo
bars

DataDome CAPTCHA
and CapMonster Cloud

CAPTCHA solution, website integration, and testing.
Inherited a site with a captcha or another protection layer but no access to the source code? In that case you naturally ask: which solution is installed, is it configured correctly, and how can the workflow be tested?

In this article, we have tried to answer all the key questions. The first step in solving the task is to determine which protection system is being used. To do this, you can refer to the list of popular captchas and anti-bot protection systems, where you will find visual examples and key indicators that help you quickly understand what you are dealing with.

If you discover that your site uses DataDome CAPTCHA, the next step is to study its properties and operation in more detail. In this article, you can also review the instructions on how to integrate DataDome CAPTCHA so that you fully understand how it functions on your site. This will help you not only understand the current protection, but also properly plan its maintenance.

What is DataDome
What is DataDome
DataDome is a bot and automated attack protection system that analyzes visitor behavior and network parameters to distinguish real users from malicious traffic and ensure the stable operation of a website or application.
Background
Examples of DataDome CAPTCHA
Behavior analysis
Behavior analysis
Assessment of user actions (clicks, scrolling, interaction speed).
JavaScript check
JavaScript check
Hidden verification of browser and environment.
Network check
Network check
Analysis of IP addresses, headers, proxies, and known bot networks.
Challenge
Challenge
Showing CAPTCHA (usually a slider “Swipe right to solve the puzzle”) if the system is unsure.
How to solve DataDome CAPTCHA using CapMonster Cloud
When testing DataDome protection, it is important to ensure that it is correctly integrated and responds to suspicious traffic. For manual verification, open a page protected by DataDome and make sure the system is active.
Try making a request that simulates suspicious behavior (e.g., too frequent page refreshes or submitting a form without valid data) — DataDome should block access or show a protection page.
For automated testing and CAPTCHA solving, specialized services such as CapMonster Cloud can be used — a tool that accepts CAPTCHA parameters, processes them on its servers, and returns a ready solution. This solution (token or cookie) can be inserted into a form or browser to pass verification without user intervention.

Working with CapMonster Cloud via API typically involves the following steps:

Creating a taskCreating a task
arrow
Sending an API requestSending an API request
arrow
Receiving the resultReceiving the result
arrow
Placing the token on the pagePlacing the token on the page
arrow
DataDome CAPTCHA recognition using ready-made libraries
CapMonster Cloud provides ready-made libraries for convenient use in Python and JavaScript (Node.js).
Python
JavaScript
Solving DataDome and inserting cookies
Example in Node.js for the full cycle of CAPTCHA recognition on your web page. Possible approaches: use HTTP requests to get HTML and protection parameters, submit the answer and process the result; or use automation tools (e.g., Playwright) — open the page, wait for verification, send parameters via CapMonster Cloud client, get the result, insert cookies into the browser (for testing you can use both correct and incorrect data), and see the outcome.

// npx playwright install chromium

import { chromium } from 'playwright';
import { CapMonsterCloudClientFactory, ClientOptions, DataDomeRequest } from '@zennolab_com/capmonstercloud-client';

// Enter your CapMonster Cloud API key
const API_KEY = 'YOUR_API_KEY';

// Your site is protected by DataDome
const TARGET_URL = 'https://example.com/';

const USER_AGENT = Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)

// Proxy configuration
const proxy = {
  proxyType: "http",
  proxyAddress: '8.8.8.8',
  proxyPort: 8080,
  proxyLogin: 'proxyLogin',
  proxyPassword: 'proxyPassword'
};

async function main() {

  // Launch browser
  const browser = await chromium.launch({ headless: true });
  const context = await browser.newContext({ userAgent: USER_AGENT });
  const page = await context.newPage();

  // Go to the website
  await page.goto(TARGET_URL, { waitUntil: 'networkidle' });

  // Looking for existing datadome cookie (if any)
  const existingDd = (await context.cookies()).find(c => /datadome|dd_/i.test(c.name));

  // Find DataDome iframe -> CAPTCHA URL
  const captchaUrl = await page.evaluate(() =>
    Array.from(document.querySelectorAll('iframe[src]'))
      .find(i => /captcha-delivery\.com\/captcha/i.test(i.src))
      ?.src || null
  );

  console.log(`=== Extracted DataDome parameters ===`);
  console.log(`captchaUrl:`, captchaUrl || 'not found');
  console.log(`current datadome cookie::`, existingDd ? ${existingDd.name}=${existingDd.value}` : 'none');

  const cm = CapMonsterCloudClientFactory.Create(
    new ClientOptions({ clientKey: API_KEY })
  );

  // Send task to CapMonster
  console.log(`Sending DataDome task to CapMonster......`);

  // Submitting DataDome task for solving
  const solve = await cm.Solve(new DataDomeRequest({
    _class: "DataDome",
    websiteURL: TARGET_URL,
    userAgent: USER_AGENT,
    proxy,
    metadata: {
      captchaUrl: captchaUrl || undefined,
      datadomeCookie: existingDd
        ? `${existingDd.name}=${existingDd.value}`
        : undefined
    }
  }));

  const sol = solve?.solution;

  // Get domain and required cookies from the solution
  const host = new URL(TARGET_URL).hostname;
  const domainKey =
    Object.keys(sol.domains).find(d => d.includes(host))
    || Object.keys(sol.domains)[0];

  const cookiesArr = sol.domains[domainKey]?.cookies || [];

  console.log(`\n=== Cookies from CapMonster ===`);
  cookiesArr.forEach(c => console.log(`${c.name}=${c.value}`));

  const ddSolved =
    cookiesArr.find(c => c.name?.toLowerCase() === 'datadome')
    || cookiesArr.find(c => /datadome/i.test(c.name));

  // Set datadome cookie in browser
  await context.addCookies([{
    name: 'datadome',
    value: ddSolved.value,
    domain: '.' + host,
    path: '/',
    httpOnly: ddSolved.httpOnly ?? true,
    secure: ddSolved.secure ?? true,
    sameSite: ddSolved.sameSite ?? 'Lax'
  }]);

  console.log(`Datadome cookie set:`, ddSolved.value);

  // Reopen site after inserting cookie
  const page2 = await context.newPage();
  const resp2 = await page2.goto(TARGET_URL, { waitUntil: 'domcontentloaded', timeout: 60000 });

  console.log(`Status after setting cookie:: ${resp2?.status()}`);

  await browser.close();
}

main();
  
How to integrate DataDome CAPTCHA into your website
To confidently work with CAPTCHA on your site, understand its verification logic, or reconnect/reconfigure it, we recommend reading this section. It describes the integration process and helps you understand all details quickly.

1. Log into your account or sign up with DataDome and obtain the keys (client-side and server-side).

Important: registration requires a corporate email from your company.

After registration, you will enter the admin panel.

2. Add your site (domain) in the DataDome panel.

Add your domain to the system and choose protection parameters:

  • Web Protection (HTTP traffic protection)
  • Bot detection & mitigation
  • Frequency & behavior analysis
  • Challenge pages (DataDome verification page)
  • JS tag configuration

3. Install server-side integration.

Use Protection API or select a ready-made module for your stack (Node.js / Express, Nginx, Cloudflare, Java (Tomcat/Jetty/Vert.x), Go, etc.).

Install the official DataDome SDK/middleware and configure the server key (server-side key).

Example of DataDome integration in Node.js:

DataDome protects the server from bots and suspicious requests, automatically showing a challenge when necessary. The module can be used with Express or the built-in HTTP server Node.js.

Installation

For Express:

npm install @datadome/module-express

For Node.js HTTP module:

npm install @datadome/module-http

Node.js version 18 and above is supported. Server-side key from your DataDome panel is required.

Express integrationExpress integration
arrow
Node.js HTTP server integrationNode.js HTTP server integration
arrow

Module settings

You can pass configuration when creating the client:


const datadomeClient = new DatadomeExpress('YOUR_SERVER_KEY', {
  timeout: 150, // timeout in ms after which request is allowed
  urlPatternInclusion: null, // which URLs to check
  urlPatternExclusion: /\.(avi|flv|mka|mkv|mov|mp4|mpeg|mpg|mp3|flac|ogg|ogm|opus|wav|webm|webp|bmp|gif|ico|jpeg|jpg|png|svg|svgz|swf|eot|otf|ttf|woff|woff2|css|less|js|map|json|avif|xml|gz|zip)$/i,
  endpointHost: 'api.datadome.co',
});

Advanced options:

  • Logging DataDome headers (enrichedHeaders)
  • CSP nonce: app.use(datadomeClient.middleware({ nonce: 'VALUE' }))
  • Override request metadata via handlers

HelpIcon

More details on server-side integration in official documentation.

4. Integrate client-side.

Insert JS Tag into the <head> of your website:


<head>
  <script>
    window.ddjskey = 'YOUR_DATADOME_JS_KEY';
    window.ddoptions = {
      // Add your settings here (optional)
    };
  </script>
  <script src="https://js.datadome.co/tags.js" async></script>
  <!-- Other head elements -->
</head>

YOUR_DATADOME_JS_KEY → Replace with your Client-Side key.

Load script early in <head> to allow DataDome to intercept requests and track user behavior correctly.

If using CSP, add the following directives:

For inline scriptFor inline script
arrow
For loading external scriptsFor loading external scripts
arrow

HelpIcon

More details on client-side integration in official DataDome CAPTCHA documentation.

Check result

DataDome creates the datadome= cookie after a successful verification. This cookie is automatically sent by the user — and the server allows the request. If the cookie is missing or invalid, DataDome will show the challenge again.

Background
Possible errors and debugging
Bug Icon
Invalid key or domain
DataDome is not properly protecting the site; challenge does not appear. Ensure the correct Server-Side Key is used and the domain is added in the DataDome panel.
Bug Icon
Request processing timeout
The server did not wait for a response from the DataDome API. Increase the timeout value in the module settings.
Bug Icon
Empty token or invalid parameter
Error submitting verification result to the server. Make sure the client-side JS tag is correctly installed and returns the ddtoken.
Bug Icon
Challenge not passed
The request was flagged as suspicious or the token has expired. Enable logging using the module's logger parameter and track blocked and valid events for diagnosis.
Protection resilience checks
Security and optimization tips
Store the <b>Server-Side Key</b> only on the server; do not pass it to the client.
Store the Server-Side Key only on the server; do not pass it to the client.
Enable event logging via <b>logger</b> or <b>blocked/valid</b> listeners to track reasons for blocks.
Enable event logging via logger or blocked/valid listeners to track reasons for blocks.
Place links to the <b>Privacy Policy</b> and <b>DataDome Terms of Use</b> on form pages, as recommended for transparency to users.
Place links to the Privacy Policy and DataDome Terms of Use on form pages, as recommended for transparency to users.
Conclusion

If you’ve taken over a website that already has a captcha or another protection system installed, but you don’t have access to the code, don’t worry! It’s quite easy to identify which technology is being used. To verify that everything works correctly, you can use the CapMonster Cloud recognition service in an isolated test environment to make sure that the token processing mechanism and the validation logic are functioning properly.

In the case of DataDome CAPTCHA, it’s enough to detect the system, observe its behavior, and confirm that the protection is working correctly. In this article, we showed how to identify DataDome CAPTCHA and where to find instructions on how to integrate or reconfigure it, so you can confidently maintain the protection and keep its operation under control.

Conclusion
Helpful links
DocIconDataDome CAPTCHA DocumentationDocIconCapMonster Cloud Documentation (working with DataDome CAPTCHA)