How to set up automatic answer retrieval using pingback

Introduction

This guide is for developers who are integrating the 2Captcha API and want to receive captcha solving results automatically, without constantly polling the getTaskResult method. We will walk through how to set up a pingback (callback), register your domain, handle incoming requests, and avoid common pitfalls.

What you will need:

• Any programming language that supports HTTP requests
• An API key from 2Captcha
• A publicly accessible server or webhook endpoint to receive POST requests
• Basic familiarity with FormData and URLencoded data

1. Pingback basics

1.1. What is a pingback

A pingback (also called a callback or webhook) is a mechanism that automatically delivers captcha solving results to your server. Instead of repeatedly polling https://2captcha.com/res.php, you provide a URL where 2Captcha will send the response as soon as the captcha is solved.

1.2. Why pingback beats polling

1.3. Incoming request format

2Captcha sends data as application/x-www-form-urlencoded with two parameters:

• id — the task ID you received when creating the captcha request
• code — the solving result (token, answer, or error code)

Example request body from the docs:

id=51555263943&code=ANSWER

2. Setting up your environment

2.1. Registering your domain or IP

Before using pingback, you must register the address that will receive the responses. You can do this via the web interface or by making API requests to https://2captcha.com/res.php.

GET parameters for pingback management:

Example requests from the docs:

Add a new address:

https://2captcha.com/res.php?key=1abc234de56fab7c89012d34e56fa7b8&action=add_pingback&addr=https://mysite.com/test.php

Get a list of registered addresses:

https://2captcha.com/res.php?key=1abc234de56fab7c89012d34e56fa7b8&action=get_pingback&json=1

Delete all registered addresses:

https://2captcha.com/res.php?key=1abc234de56fab7c89012d34e56fa7b8&action=del_pingback&addr=all

Important: You can only add a domain or IP from the same address it points to. This is a security measure to prevent unauthorized registration.

2.2. Getting your API key

1. Sign up at 2captcha.com
2. Go to your account settings
3. Copy your API key
4. Store the key in an environment variable (recommended)

3. Analyzing and extracting parameters

3.1. Choosing your pingback URL

Pick a publicly accessible endpoint that will receive notifications. Examples:

• https://api.yourservice.com/captcha/callback
• https://123.123.123.123/pingback
• https://mysite.com/hook?service=2captcha

3.2. Important limitation for GET requests

If you submit a captcha via a GET request to https://api.2captcha.com/in.php and your pingback URL contains multiple parameters, for example:

https://mysite.com/pingback/?myId=1&myCat=2&something_else=test

— only the first parameter ?myId=1 will be preserved and used.

Solution: Use POST requests with multipart/form-data when submitting tasks if your callback URL contains parameters.

4. Implementation

4.1. Sending a task with pingback

Add the pingback parameter to your request to https://2captcha.com/in.php. Example from the docs:

key=YOUR_API_KEY&method=userrecaptcha&googlekey=SITE_KEY&pageurl=PAGE_URL&pingback=https://mysite.com/pingback

4.2. Handling incoming requests

Your server must accept POST requests with content type application/x-www-form-urlencoded. The request contains two parameters:

• id — the captcha task ID
• code — the captcha answer

Example incoming request:

id=51555263943&code=ANSWER

4.3. Minimal handler (pseudocode)

Receive POST request at /pingback
Extract id and code parameters from request body
Verify request source (optional)
Process the result:
  - Save to database
  - Add to task queue
  - Notify the user
Return 200 OK status

5. Implementation notes

The pingback parameter:

• Passed in the in.php request as a regular parameter
• Value is the full URL of your handler
• Must be pre-registered via add_pingback

Handling incoming data:

• Data arrives as application/x-www-form-urlencoded
• Always check that both id and code parameters are present
• Return 200 OK to confirm receipt

Security:

• Consider verifying the sender's IP address
• Use HTTPS for your pingback endpoint
• Do not log sensitive data (tokens, keys)

Asynchronous processing:

• Your handler should respond quickly (within a few seconds)
• If processing the result takes time, queue the data and respond OK immediately

6. Alternative approaches and extra settings

6.1. Hybrid approach: pingback plus fallback polling

For maximum reliability, you can combine both methods. Send the task with pingback enabled, but if the response does not arrive within the expected time, trigger a fallback poll using getTaskResult.

6.2. Passing extra parameters

You can add your own parameters to the pingback URL:

https://mysite.com/pingback?user_id=123&session=abc

Remember the GET request limitation. If you submit the task via GET, only the first parameter will be preserved. To pass multiple parameters, use POST with multipart/form-data.

6.3. Monitoring solve time

To implement alerts (as in the original user request), measure the time between sending the task and receiving the pingback. If the interval exceeds your threshold, send a notification to your monitoring system.

7. Pingback handler requirements

8. Common issues and fixes

8.1. Debugging pingback

To troubleshoot issues, enable logging on your handler:

• Log incoming requests (without sensitive data)
• Check Content-Type and User-Agent headers
• Test your handler locally using tools like curl or Postman

9. Additional resources

• Address management: Pingback management page on 2captcha.com
  Add and edit URLs to receive responses

• API reference: api-docs.2captcha.com
  Full documentation of all API methods and parameters

• Support: Create a ticket
  Need help, reach out to support, we are here for you

10. Pre-launch checklist

• Domain or IP registered for pingback via add_pingback
• Handler accepts POST requests with application/x-www-form-urlencoded
• Handler extracts id and code parameters from request body
• Handler returns 200 OK after receiving data
• HTTPS enabled for pingback endpoint
• Source verification implemented (optional but recommended)
• Task submission with pingback parameter tested
• Logging configured for debugging
• Asynchronous result processing implemented (if needed)
• GET request limitation with multiple URL parameters verified

Wrapping up

Pingback is a reliable way to receive captcha solving results automatically, without putting load on your account or risking rate limit issues from polling. The setup is straightforward. Register your address, add the pingback parameter to your request, and implement a POST request handler.

For tasks that require monitoring solve times (as in the original user request), pingback lets you measure intervals precisely and respond to delays in real time. Combine pingback with fallback polling for maximum reliability.

If you have questions about integration, reach out to 2Captcha support. The team will help you set up pingback for your specific use case.