人工交接与 Webhook
有些步骤需要人来完成:CAPTCHA、发到手机上的验证码、只有账号所有者才能给出的授权。人工交接通过一个链接把正在运行的浏览器交给某个人,等对方完成后再收回,既适用于你自己驱动的会话,也适用于智能体任务。Webhook 会在有事情发生时通知你的服务器,并带有签名,方便你确认请求确实来自我们。
交给人工处理
对正在运行的会话调用 POST /api/v1/browsers/<id>/handoff,会返回一个实时链接。打开链接的人无需账号即可看到浏览器,并在其中点击、输入和滚动。完成后,对方在该页面上点击“I'm done”,你的代码就会在同一个浏览器中继续运行,对方所做的一切(通过的验证、已登录的账号)都会保留。
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.requestedWebhook 中。对方打开的页面只显示一条标准提示(“接管操作,完成后点击 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.requestedWebhook 中带有相同的liveUrl,因此 Webhook 处理程序可以直接转发链接(发到聊天、邮件或工单),无需你的脚本处理。
GET /api/v1/browsers/<id> 会显示交接情况。在你请求交接之前,handoff 为 null;除非 state 为 waiting,否则 liveUrl 为 null。如果 expiresAt 已过而对方没有点击“I'm done”,或会话已先结束,state 会变为 timeout,链接随之失效。你自己驱动的会话会继续运行;智能体任务则会结束(见下文)。
"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。
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 并新建一个。
# 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,之后再处理具体工作。
事件
| type | data | 发送时机 |
|---|---|---|
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。
投递内容示例
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 的密钥签名:
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 "", 204verify_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 标准库的写法如下:
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)手动验证一条已保存的投递:
# 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