Integration Documentation

Netacea CAPTCHA Feedback


Inject mode allows Netacea to set upstream headers on a user’s request containing our recommended action (i.e. hard block or CAPTCHA). This allows the customer to either report or act on our recommendations without Netacea handling it for them.
Our mitigation service events will contain information about the blocklist lookups, but the status of the user could have changed given the client’s intervention and we would not have information about it. A mechanism is required through which the client can feedback to us about the outcome of a CAPTCHA invocation so that our user states can be kept up to date and our reporting lines up with this status. This is where the captchafeedback package comes into play.


1: Initial block recommendation

  1. 1.
    User makes a request with/without an existing _mitata cookie.
  2. 2.
    Relevant integration makes request out to the Netacea mitigations service.
  3. 3.
    Response from mitigations service indicates that the user should be blocked (X-Netacea-{Match, Mitigate, Captcha} headers.
  4. 4.
    The upstream request has the X-Netacea-{Match, Mitigate, Captcha} headers attached to indicate to the backend that this user should be served CAPTCHA. The user's new session cookie is also appended to the inflight response.
  5. 5.
    eventid is also attached to allow full traceability back to the blocking decision in Netacea.
  6. 6.
    Client application responds to the use, challenging them if they see fit.

2: Verification

  1. 1.
    User carries out verification (CAPTCHA in this case). The Netacea block ID is returned to the backend as well.
  2. 2.
    Backend calls out to mitigations API with details of the client request and the verification output.
  3. 3.
    Mitigations API returns new _mitata and _mitatacaptcha cookie for the user, which the backend would have to set on the inflight request. 

API Call Schema

The POST body will take two fields, the result of which will be a Boolean value and eventId which will be the eventId from the served CAPTCHA response. The format accepted will be JSON. We will need the standard headers X-Netacea-API-Key X-Netacea-Client-IP, User-Agent and the cookie header.


The mitigation service will accept POST requests on the /UpdateCaptcha endpoint.

Netacea CAPTCHA Feedback Package

@netacea/captchafeedback is a package designed to add Netacea CAPTCHA feedback functionality to your NodeJS based origin server.


npm i @netacea/captchafeedback --save
yarn add @netacea/captchafeedback


import Netacea from '@netacea/captchafeedback'
const netacea = new Netacea({
apiKey: 'your-api-key'
const { cookies } = await netacea.updateCaptcha({
clientIp: 'client-ip', // Client's real IP address
cookieHeader: 'cookie-header', // Incoming cookie header value
eventId: 'captcha-page-event-id', // X-Netacea-Event-ID received when captcha was served
result: true, // Result from captcha
userAgent: 'client-user-agent' // Client's user-agent
Copyright Netacea 2023