Skip to main content
When using asynchronous requests, the Unlocker API processes jobs in the background.Instead of polling for results, you can configure a webhook. A webhook is an HTTP endpoint that Bright Data calls when your job is completed.The flow looks like this:
  1. Send async request
  2. Receive response_id
  3. Bright Data processes the request
  4. Bright Data sends a notification to your webhook_url
  5. Use the response_id to retrieve the result
Webhooks notify you when a job is ready, they do not include the full response body.
1

Create a webhook endpoint

You need a publicly accessible URL to receive webhook notifications.
For demonstration purposes, we’ll use webhook.site.It instantly generates a temporary webhook URL and lets you inspect incoming requests in real time, including headers, query parameters, and payloads.
2

Send an async request with webhook

Add the webhook_url parameter to your request:
cURL
curl --request POST \
  --url 'https://api.brightdata.com/unblocker/req?zone=<unlocker-zone-name>' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://geo.brdtest.com/welcome.txt",
    "webhook_url": "https://webhook.site/<webhook-url-id>",
  }'
Replace <API_KEY>, <unlocker-zone-name>, <webhook-url-id> with your actual values.
3

Receive webhook notification

Once the request is processed, Bright Data sends a POST request to your webhook_url.
// A typical webhook request includes:
{
  "status": 200,
  "response_id": "<RESPONSE_ID>",
  "request_url": "https://geo.brdtest.com/welcome.txt"
}
If you’re using webhook.site, you can inspect the incoming request, including payload fields and headers (e.g., user-agent).
This webhook notifies you that the request has completed.
4

Retrieve the result using response_id

Use the response_id from the webhook to fetch the actual result:
curl --silent --compressed \
  "https://api.brightdata.com/unblocker/get_result?response_id=<RESPONSE_ID>" \
  -H "Authorization: Bearer <API_KEY>" \
  -o results.json
Then inspect the output:
cat results.json
The file will contain the full response, including headers and body.
5

Optional Attach custom data to webhook

You can include custom metadata using webhook_data. When using webhook_method as POST, this data will be sent in the request body of the webhook notification.
curl --request POST \
  --url 'https://api.brightdata.com/unblocker/req?zone=web_unlocker3' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://geo.brdtest.com/welcome.txt",
    "webhook_url": "https://webhook.site/a14a55b3-c3cc-4890-84f2-eeebe4b264a4",
    "webhook_method": "POST",
    "webhook_data": "{\"job_id\": \"my_job_123\", \"source\": \"test_script\"}"
  }'
The webhook_data field is returned unchanged in the webhook notification. This allows you to attach identifiers such as job IDs or metadata, making it easier to map responses to your internal workflows.

Congratulations

You’ve successfully set up webhooks with the Unlocker API. You can now receive real-time notifications for completed jobs and build more efficient, event-driven scraping workflows.