跳到正文

人工交接与 Webhook

有些步骤需要人来完成:CAPTCHA、发到手机上的验证码、只有账号所有者才能给出的授权。人工交接通过一个链接把正在运行的浏览器交给某个人,等对方完成后再收回,既适用于你自己驱动的会话,也适用于智能体任务。Webhook 会在有事情发生时通知你的服务器,并带有签名,方便你确认请求确实来自我们。

交给人工处理

对正在运行的会话调用 POST /api/v1/browsers/<id>/handoff,会返回一个实时链接。打开链接的人无需账号即可看到浏览器,并在其中点击、输入和滚动。完成后,对方在该页面上点击“I'm done”,你的代码就会在同一个浏览器中继续运行,对方所做的一切(通过的验证、已登录的账号)都会保留。

bash
curl -X POST -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
  -d '{"reason": "captcha on the login page", "timeoutSec": 900}' \
  https://www.clearcotelabs.com/api/v1/browsers/<id>/handoff
# {
#   "state": "waiting",
#   "reason": "captcha on the login page",
#   "since": "2026-10-02T09:30:00.000Z",
#   "expiresAt": "2026-10-02T09:45:00.000Z",
#   "liveUrl": "https://www.clearcotelabs.com/live/bs_…?handoff=1#t=…"
# }

# end it from your side instead of the button
curl -X POST -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>/handoff/done
# { "state": "done", "reason": "…", "since": "…", "expiresAt": "…", "doneAt": "…", "liveUrl": null }
  • reason(可选,单行,最多 500 个字符)是写给你和你的 Webhook 处理程序的备注:它会出现在响应、会话视图、仪表盘以及 handoff.requested Webhook 中。对方打开的页面只显示一条标准提示(“接管操作,完成后点击 I'm done”),所以发送链接时请说明需要做什么。timeoutSec 是 60 到 3600 之间的整数,默认 600:链接在 expiresAt 之前有效。
  • 令牌位于 liveUrl 中的 # 之后,因此不会出现在任何服务器日志里。请完整转发该链接。
  • 会话必须处于运行状态,否则返回 409 NOT_RUNNING。较旧服务器上的浏览器会返回 409 HANDOFF_UNSUPPORTED,此时请启动一个新会话。在交接等待期间再次请求,会返回同一个交接,其链接、原因和 expiresAt 均保持不变。
  • 重复标记完成会得到相同的响应。如果从未请求过交接,返回 409 NO_HANDOFF;如果交接已先行超时,返回 409 HANDOFF_EXPIRED。
  • 交接等待期间,即使你的脚本和对方都没有任何操作,会话也不会因空闲而被关闭。会话本身的 timeoutSec(创建时设定)、maxGb 和你的余额仍然有效。交接完成或超时后,空闲超时从那一刻起重新计时。
  • 该链接是控制链接:任何拿到它的人都可以在其过期前操作浏览器,身份就是浏览器当前登录的账号。请只发给需要操作的人。
  • handoff.requested Webhook 中带有相同的 liveUrl,因此 Webhook 处理程序可以直接转发链接(发到聊天、邮件或工单),无需你的脚本处理。

GET /api/v1/browsers/<id> 会显示交接情况。在你请求交接之前,handoff 为 null;除非 state 为 waiting,否则 liveUrl 为 null。如果 expiresAt 已过而对方没有点击“I'm done”,或会话已先结束,state 会变为 timeout,链接随之失效。你自己驱动的会话会继续运行;智能体任务则会结束(见下文)。

json
"handoff": {
  "state": "waiting",           // waiting | done | timeout
  "reason": "captcha on the login page",
  "since": "2026-10-02T09:30:00.000Z",
  "expiresAt": "2026-10-02T09:45:00.000Z",
  "doneAt": null,
  "liveUrl": "https://www.clearcotelabs.com/live/bs_…?handoff=1#t=…"
}

在脚本中使用

交接期间你的脚本保持连接。等对方完成后再继续:

from playwright.sync_api import sync_playwright
from clearcote.cloud import Cloud

cloud = Cloud()
session = cloud.browsers.create(country="de", profile={"name": "shop-account", "persist": True})

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(session["connectUrl"], timeout=120_000)
    page = browser.contexts[0].new_page()
    page.goto("https://shop.example.com/login")

    if page.get_by_text("Verify you are human").count():
        h = cloud.browsers.handoff(session["id"], reason="captcha on the login page", timeout_sec=900)
        print("Send this link:", h["liveUrl"])
        view = cloud.browsers.wait_handoff(session["id"])   # returns once it is done, or has timed out
        if view["handoff"]["state"] != "done":
            raise SystemExit("nobody finished the check in time")

    page.goto("https://shop.example.com/orders")
    browser.close()

wait_handoff / waitHandoff 每 2 秒轮询一次 GET /api/v1/browsers/<id>,直到 handoff.state 不再是 waiting,然后返回该会话视图。传入 timeout(秒)可以提前停止等待:此时会抛出 CloudTimeoutError,交接仍保持打开。若要从你这一侧结束交接,而不是等对方点击按钮,请调用 cloud.browsers.handoff_done(id)(Node:handoffDone(id))。不使用 SDK 时,每隔几秒轮询一次 GET /api/v1/browsers/<id>,直到 handoff.state 变为 done(或 timeout),或者等待 handoff.done Webhook。交接超时不会发送 Webhook,所以到了 expiresAt 也要停止等待。

在智能体任务中使用

创建任务时设置 handoff: true。当 Jet 因缺少所需信息(needs_input)或无法继续推进(blocked)而停止时,任务不会结束,而是暂停为 waiting_for_human,任务的 handoff 中包含 liveUrl,并发出一个 handoff.requested Webhook。

bash
curl -X POST https://www.clearcotelabs.com/api/v1/runs \
  -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
  -d '{"task": "Open Orders and read the latest order number", "url": "https://shop.example.com/orders",
       "profile": {"name": "shop-account", "persist": true}, "handoff": true, "handoffTimeoutSec": 1800,
       "timeoutSec": 3600}'
  • 对方点击“I'm done”后,Jet 会在同一页面上以同一任务重新开始,看到的页面就是对方离开时的样子(如果对方关闭了该标签页,则从任务的 url 重新开始)。
  • 一个任务最多可以交接三次。result.handoffs 记录交接次数,交接前后的所有步骤都在 result.steps 中。
  • handoffTimeoutSec(60 到 3600,默认 600)是每次交接的等待时长。如果没人按时完成,任务会以 Jet 停止时的状态结束,也就是 failed。任务本身的 timeoutSec(默认 900)在交接期间仍会计时:调大 handoffTimeoutSec 时,也要相应调大它。
  • 请配合 profile 和 persist: true 使用:对方登录的状态会被保存,下一次任务就不再需要人工介入。

Webhook

Webhook 是你提供的一个 URL,有事情发生时,我们会向它发送一个带签名的 POST 请求。可以通过 API、SDK、CLI 或仪表盘设置创建:

curl -X POST https://www.clearcotelabs.com/api/v1/webhooks \
  -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
  -d '{"url": "https://example.com/hooks/clearcote", "events": ["run.finished", "handoff.requested"], "description": "prod"}'
# {
#   "id": "wh_…",
#   "url": "https://example.com/hooks/clearcote",
#   "events": ["run.finished", "handoff.requested"],
#   "description": "prod",
#   "createdAt": "…",
#   "secret": "whsec_…"       <- shown once: store it now
# }

secret 只出现在创建时的响应中,用于验证签名。如果丢失,请删除该 Webhook 并新建一个。

bash
# your webhooks, with the last delivery attempt of each
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/webhooks
# { "webhooks": [ { "id": "wh_…", "url": "…", "events": [ … ], "description": "prod", "createdAt": "…",
#                   "lastDelivery": { "at": "…", "status": 200, "ok": true } } ] }

# send a ping to it now (once, never retried)
curl -X POST -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/webhooks/<id>/test
# { "id": "evt_…", "ok": true, "status": 200 }

# delete it (retries still waiting for it are dropped)
curl -X DELETE -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/webhooks/<id>
# { "ok": true }

在发送过任何内容之前,lastDelivery 为 null。它的 status 以及测试的 status,是你的服务器返回的 HTTP 状态码;没有响应时为 null。测试失败时还会带有说明原因的 error。即使 events 中没有列出 ping,也会发送测试 ping。

规则

  • 每个账号最多 5 个 Webhook,创建第 6 个会返回 409 WEBHOOK_LIMIT。description 为单行,最多 200 个字符。
  • events 用于选择要发送的事件(见下表)。省略它或传入空列表,则发送除 ping 以外的所有事件。
  • URL 必须使用 https://,最长 2048 个字符,不能包含用户名或密码,并且必须位于公网上。localhost、单标签名称(如 https://intranet),以及位于私有、环回、链路本地、运营商级 NAT、组播、文档、保留或云元数据地址段中的 IP 地址,都会在创建 Webhook 时被拒绝;内嵌 IPv4 地址的 IPv6 地址(::ffff:…)同样会被拒绝。每次投递时都会解析主机名:只要其任一地址落在这些地址段中,就不会发送任何内容,并且该次尝试计为失败。
  • 不跟随重定向,每次尝试最多等待 5 秒响应。请尽快返回 2xx,之后再处理具体工作。

事件

typedata发送时机
session.started{ id, kind: "cdp" | "run", worker }浏览器已启动。由你驱动的会话,kind 为 "cdp";智能体任务则为 "run"。
session.ended{ id, kind, reason, usage: { bytesUp, bytesDown, seconds }, costEur }会话已结束,包含结束原因和用量。costEur 是一个数字:对智能体任务而言是浏览器与智能体费用之和。处于 lost 状态且再也没有上报的会话,会在被最终结束时发送此事件,原因为 worker_silent;若其服务器在重启后恢复,则原因为 worker_restarted。
run.finished{ id, status, result: { status, detail, url, title, output, outputError }, costEur }智能体任务已结束。status 为 succeeded、failed 或 cancelled;result 是其结果的主要部分,没有结果时为 null;costEur 为 { browser, agent, total }。
handoff.requested{ id, kind, reason, liveUrl, expiresAt }浏览器已交给人工处理。请把 liveUrl 发给需要操作的人。
handoff.done{ id, kind }对方点击了“I'm done”,或你将其标记为完成(通过 API 或仪表盘)。交接超时不会发送此事件。
recording.ready{ id, bytes, durationSec }录像已可下载。
ping{}由测试调用发送,用于检查你的端点。

data 中的 id 是会话或任务的 id(两者是同一个东西)。需要事件之外的更多信息时,可以通过 GET /api/v1/runs/<id> 或 GET /api/v1/browsers/<id> 获取完整状态。排队中的任务如果在被服务器接手前被取消或过期,既不会发送 session.ended,也不会发送 run.finished。

投递内容示例

http
POST /hooks/clearcote HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Clearcote-Webhooks/1
Clearcote-Webhook-Id: evt_…
Clearcote-Signature: t=1790932461,v1=6a1f0c…

{
  "id": "evt_…",
  "type": "run.finished",
  "createdAt": "2026-10-02T09:14:21.312Z",
  "data": {
    "id": "bs_…",
    "status": "succeeded",
    "result": {
      "status": "done",
      "detail": null,
      "url": "https://www.gov.uk/bank-holidays",
      "title": "UK bank holidays - GOV.UK",
      "output": { "name": "Christmas Day", "date": "2026-12-25" },
      "outputError": null
    },
    "costEur": { "browser": …, "agent": …, "total": … }
  }
}

重试

你的服务器返回 2xx 时,投递才算成功。其他任何情况(其他状态码、重定向、超时、连接被拒绝)都会重试。总共尝试 6 次:立即一次,然后在事件发生后约 30 秒、2 分钟、10 分钟、1 小时和 6 小时各一次。第 6 次之后,该投递会被标记为失败,并显示在 lastDelivery 中。测试 ping 只发送一次,不会重试。

  • 要预期会有重复。同一投递可能到达不止一次,例如你的响应丢失时。Clearcote-Webhook-Id(即外层信封的 id)在每次尝试中都相同:跳过已经处理过的 id 即可。
  • 不要依赖顺序。重试的事件可能晚于之后发生的事件到达。请使用 createdAt,或获取当前状态。

验证签名

每次投递都使用该 Webhook 的密钥签名:

text
Clearcote-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the secret as key>

验证时,对原始请求体(未经任何 JSON 解析的原始字节)计算同样的 HMAC,以恒定时间与 v1 比较,并拒绝与当前时间相差超过 5 分钟的 t,以防旧的投递被重放。SDK 用一次调用即可完成以上全部步骤:

import os
from flask import Flask, abort, request
from clearcote.cloud import verify_webhook

app = Flask(__name__)
SECRET = os.environ["CLEARCOTE_WEBHOOK_SECRET"]   # whsec_...

@app.post("/hooks/clearcote")
def clearcote_hook():
    try:
        event = verify_webhook(request.get_data(), request.headers.get("Clearcote-Signature", ""), SECRET)
    except ValueError:
        abort(400)                                 # bad or old signature
    if event["type"] == "run.finished":
        data = event["data"]
        print(data["id"], data["status"], data["result"]["output"])
    return "", 204

verify_webhook(raw_body, signature_header, secret, tolerance_sec=300)(也可以从 clearcote 导入)返回解析后的事件;当请求头缺失或格式错误、签名不匹配或 t 超出范围时,抛出 ValueError。在 Node 中,verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) 以同步方式完成同样的工作,并抛出 Error。raw_body 可以是字节或字符串,整个 whsec_… 字符串就是密钥,多个 v1 值中只要有一个匹配即可。密钥缺失或为空也会报错,因此未设置的环境变量不会让任何投递通过验证。如需跳过时间检查(例如重放已保存的投递),请传入 tolerance_sec=None(Node:null)。

任意语言

不需要 SDK:这只是一个普通的 HMAC-SHA256,以完整的密钥字符串(包括 whsec_)作为密钥。仅用 Python 标准库的写法如下:

python
import hashlib, hmac, json, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> dict:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, sig = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        raise ValueError("missing or old timestamp")
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        raise ValueError("bad signature")
    return json.loads(raw_body)

手动验证一条已保存的投递:

bash
# T = the t= value of the header, body.json = the raw body exactly as received
{ printf '%s.' "$T"; cat body.json; } | openssl dgst -sha256 -hmac "$CLEARCOTE_WEBHOOK_SECRET"
# the hex at the end must equal the v1= value

更新于 2026年10月12日 · SDK 0.70.5 · 浏览器 r63

这个页面有帮助吗?