> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何为 Web Unlocker API 设置 Webhooks

<AccordionGroup>
  <Accordion title="了解 webhooks 的工作原理" icon="lightbulb" color="#4CAF50" iconType="duotone">
    使用[异步请求](/api-reference/rest-api/unlocker/request)时，Web Unlocker API 在后台处理作业。

    您可以配置一个 webhook，而不是轮询结果。Webhook 是一个 HTTP 端点，当您的作业完成时，Bright Data 会调用它。

    流程如下：

    1. 发送异步请求
    2. 接收 `response_id`
    3. Bright Data 处理请求
    4. Bright Data 向您的 `webhook_url` 发送通知
    5. 使用 `response_id` 检索结果

    <Tip>
      Webhooks 通知您作业何时准备就绪，但不包括完整的响应正文。
    </Tip>
  </Accordion>

  <Accordion title="前置条件" icon="list-check" iconType="duotone">
    以下为必需项：

    * [Bright Data 账户](https://www.bright.cn/?hs_signup=1\&utm_source=docs)
    * [Bright Data API 密钥](https://localhost:3000/api-reference/authentication#how-do-i-generate-a-new-api-key)
    * [活跃的 Web Unlocker API 区域](https://www.bright.cn/cp/zones)
    * [cURL 基础知识](https://curl.se/)
    * [使用 Web Unlocker API 的工作异步请求设置](/cn/products/web-unlocker/send-your-first-request#发送您的第一个异步请求)
  </Accordion>
</AccordionGroup>

<Steps>
  <Step title="创建 webhook 端点">
    您需要一个可公开访问的 URL 来接收 webhook 通知。

    <Tip>
      为了演示目的，我们将使用 [webhook.site](https://webhook.site)。

      它可以立即生成一个临时 webhook URL，并让您实时检查传入的请求，包括标头、查询参数和有效负载。
    </Tip>
  </Step>

  <Step title="发送带有 webhook 的异步请求">
    将 `webhook_url` 参数添加到您的请求：

    <CodeGroup dropdown>
      ```bash cURL theme={null}
      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>",
        }'
      ```

      ```python Python theme={null}
        import requests

        url = "https://api.brightdata.com/unblocker/req?zone=<unlocker-zone-name>"

        payload = {
            "url": "https://geo.brdtest.com/welcome.txt",
            "webhook_url": "https://webhook.site/<webhook-url-id>",
        }
        headers = {
            "Authorization": "Bearer <API_KEY>",
            "Content-Type": "application/json"
        }

        response = requests.post(url, json=payload, headers=headers)

        print(response.text)
      ```

      ```js Node.js theme={null}
      const options = {
        method: 'POST',
        headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
        body: JSON.stringify({
          url: 'https://geo.brdtest.com/welcome.txt',
          webhook_url: 'https://webhook.site/<webhook-url-id>',
        })
      };

      fetch('https://api.brightdata.com/unblocker/req?zone=<unlocker-zone-name>', options)
        .then(res => res.json())
        .then(res => console.log(res))
        .catch(err => console.error(err));
      ```
    </CodeGroup>

    <Callout color="#4CAF50" icon="key" iconType="duotone">
      将 `<API_KEY>`、`<unlocker-zone-name>`、`<webhook-url-id>` 替换为您的实际值。
    </Callout>
  </Step>

  <Step title="接收 webhook 通知">
    请求处理完成后，Bright Data 向您的 `webhook_url` 发送 POST 请求。

    ```json theme={null}
    // 典型的 webhook 请求包括：
    {
      "status": 200,
      "response_id": "<RESPONSE_ID>",
      "request_url": "https://geo.brdtest.com/welcome.txt"
    }
    ```

    如果您使用 webhook.site，可以检查传入的请求，包括有效负载字段和标头（例如 `user-agent`）。

    <Tip>
      此 webhook 通知您请求已完成。
    </Tip>
  </Step>

  <Step title={<>使用 <code>response_id</code> 检索结果</>}>
    使用 webhook 中的 `response_id` 获取实际结果：

    ```sh wrap theme={null}
    curl --silent --compressed \
      "https://api.brightdata.com/unblocker/get_result?response_id=<RESPONSE_ID>" \
      -H "Authorization: Bearer <API_KEY>" \
      -o results.json
    ```

    然后检查输出：

    ```sh theme={null}
    cat results.json
    ```

    该文件将包含完整响应，包括标头和正文。
  </Step>

  <Step title={<><Badge>可选</Badge> 将自定义数据附加到 webhook</>}>
    您可以使用 `webhook_data` 包含自定义元数据。当使用 `webhook_method` 作为 `POST` 时，此数据将在 webhook 通知的请求正文中发送。

    ```bash wrap theme={null}
    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\"}"
      }'
    ```

    `webhook_data` 字段在 webhook 通知中按原样返回。这允许您附加标识符（如作业 ID 或元数据），使将响应映射到您的内部工作流更加容易。
  </Step>

  <Step title="恭喜" icon="party-horn" iconType="duotone">
    您已成功为 Web Unlocker API 设置了 webhooks。您现在可以接收已完成作业的实时通知，并构建更高效、事件驱动的抓取工作流。
  </Step>
</Steps>