Bàn giao và webhook
Một số bước cần đến con người: một CAPTCHA, một mã gửi về điện thoại, một sự đồng ý mà chỉ chủ tài khoản mới đưa ra được. Bàn giao (hand-off) trao một trình duyệt đang chạy cho một người qua một liên kết và lấy lại khi họ xong việc, cho cả phiên do bạn điều khiển lẫn lượt chạy agent. Webhook báo cho server của bạn khi có chuyện xảy ra, có chữ ký để bạn kiểm tra rằng chúng đến từ chúng tôi.
Bàn giao cho một người
POST /api/v1/browsers/<id>/handoff trên một phiên đang chạy trả về một liên kết trực tiếp. Ai mở liên kết đó sẽ thấy trình duyệt và có thể nhấp, gõ và cuộn trong đó, không cần tài khoản. Khi xong, họ nhấn I'm done trên trang đó, và code của bạn tiếp tục trong cùng trình duyệt, với mọi thứ họ đã làm (một bước kiểm tra đã hoàn tất, một tài khoản đã đăng nhập) vẫn giữ nguyên.
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(tùy chọn, tối đa 500 ký tự trên một dòng) là ghi chú cho bạn và handler webhook của bạn: nó có trong phản hồi, trong chế độ xem phiên, trong dashboard và trong webhookhandoff.requested. Trang mà người đó mở hiển thị một thông báo chuẩn (“tiếp quản, rồi nhấn I'm done”), vì vậy hãy nói rõ cần làm gì khi bạn gửi liên kết.timeoutSeclà số nguyên từ 60 đến 3600, mặc định 600: liên kết hoạt động đếnexpiresAt.- Token nằm sau dấu
#trongliveUrl, nên không bao giờ xuất hiện trong log của server. Hãy chuyển nguyên vẹn cả liên kết. - Phiên phải đang chạy, nếu không phản hồi sẽ là
409 NOT_RUNNING. Trình duyệt trên một server cũ hơn trả về409 HANDOFF_UNSUPPORTED; hãy khởi động một phiên mới. Yêu cầu lại trong khi một lần bàn giao đang chờ sẽ trả về chính lần bàn giao đó, với liên kết, lý do vàexpiresAtkhông đổi. - Đánh dấu xong hai lần cho cùng một phản hồi. Phản hồi là
409 NO_HANDOFFnếu chưa có yêu cầu bàn giao nào, và409 HANDOFF_EXPIREDnếu nó đã hết hạn trước đó. - Trong khi một lần bàn giao đang chờ, phiên không bị đóng vì idle, kể cả khi cả script của bạn lẫn người đó đều không làm gì.
timeoutSecriêng của phiên (đặt khi bạn tạo phiên),maxGbvà số dư của bạn vẫn áp dụng. Khi lần bàn giao đã xong hoặc đã hết hạn, thời gian chờ idle được tính lại từ thời điểm đó. - Liên kết này là liên kết điều khiển: bất kỳ ai có nó đều điều khiển được trình duyệt cho đến khi hết hạn, dưới danh tính mà trình duyệt đang đăng nhập. Chỉ gửi nó cho người cần thao tác.
- Webhook
handoff.requestedmang cùngliveUrl, nên một handler webhook có thể chuyển tiếp liên kết (vào một kênh chat, một email, một ticket) mà script của bạn không cần làm việc đó.
GET /api/v1/browsers/<id> hiển thị lần bàn giao. handoff là null cho đến khi bạn yêu cầu, và liveUrl là null trừ khi state là waiting. Khi expiresAt đã qua mà không có “I'm done”, hoặc phiên đã kết thúc trước đó, state sẽ là timeout và liên kết ngừng hoạt động. Phiên do bạn điều khiển vẫn tiếp tục chạy; một lượt chạy agent thì kết thúc (xem bên dưới).
"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=…"
}Từ một script
Script của bạn vẫn giữ kết nối trong lúc bàn giao. Hãy đợi đến khi người đó xong, rồi tiếp tục:
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 gọi GET /api/v1/browsers/<id> mỗi 2 giây cho đến khi handoff.state không còn là waiting, rồi trả về chế độ xem phiên đó. Truyền một timeout (tính bằng giây) để ngừng chờ sớm hơn: khi đó nó ném ra CloudTimeoutError và lần bàn giao vẫn mở. Để kết thúc một lần bàn giao từ phía bạn thay vì bằng nút bấm, hãy gọi cloud.browsers.handoff_done(id) (Node: handoffDone(id)). Không dùng SDK thì gọi GET /api/v1/browsers/<id> vài giây một lần cho đến khi handoff.state là done (hoặc timeout), hoặc đợi webhook handoff.done. Không có webhook nào được gửi khi một lần bàn giao hết hạn, nên hãy ngừng chờ cả khi đến expiresAt.
Trong lượt chạy agent
Tạo lượt chạy với handoff: true. Khi Jet dừng vì cần một thứ nó không có (needs_input) hoặc không thể đi tiếp (blocked), lượt chạy không kết thúc: nó tạm dừng ở trạng thái waiting_for_human, handoff của lượt chạy chứa liveUrl, và một webhook handoff.requested được gửi đi.
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}'- Khi người đó nhấn “I'm done”, Jet bắt đầu lại trên cùng trang với cùng nhiệm vụ, và thấy trang đúng như họ để lại (nếu họ đã đóng tab đó, Jet bắt đầu lại ở
urlcủa lượt chạy). - Một lượt chạy có thể được bàn giao tối đa ba lần.
result.handoffsđếm số lần đó, và các bước trước và sau đều nằm trongresult.steps. handoffTimeoutSec(60 đến 3600, mặc định 600) là thời gian mỗi lần bàn giao chờ. Nếu không ai xong kịp, lượt chạy kết thúc với trạng thái mà Jet đã dừng ở đó, tức làfailed.timeoutSecriêng của lượt chạy (mặc định 900) vẫn tiếp tục tính trong lúc bàn giao: hãy tăng nó khi bạn tănghandoffTimeoutSec.- Dùng nó cùng một
profilevàpersist: true: những gì người đó đăng nhập sẽ được lưu lại, và lượt chạy tiếp theo không cần đến họ nữa.
Webhook
Webhook là một URL của bạn mà chúng tôi gửi một yêu cầu POST có chữ ký đến khi có chuyện xảy ra. Tạo webhook bằng API, SDK, CLI hoặc phần cài đặt trong dashboard:
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 chỉ có trong phản hồi khi tạo; đó là thứ bạn dùng để kiểm tra chữ ký. Làm mất? Hãy xóa webhook và tạo một cái mới.
# 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 là null cho đến khi có gì đó được gửi. status của nó, và status của một lần thử, là mã trạng thái HTTP mà server của bạn đã trả về, hoặc null khi không có phản hồi; một lần thử thất bại còn có error cho biết lý do. Ping thử vẫn được gửi kể cả khi events không có ping.
Quy tắc
- Tối đa 5 webhook cho mỗi tài khoản; webhook thứ sáu sẽ nhận
409 WEBHOOK_LIMIT.descriptiondài tối đa 200 ký tự trên một dòng. eventschọn những gì được gửi (bảng bên dưới). Bỏ trống, hoặc gửi một danh sách rỗng, để nhận mọi thứ trừping.- URL phải là
https://, dài tối đa 2048 ký tự, không chứa tên người dùng hay mật khẩu, và nằm trên internet công cộng.localhost, tên chỉ có một nhãn (nhưhttps://intranet) và địa chỉ IP trong các dải private, loopback, link-local, NAT cấp nhà mạng (CGNAT), multicast, dành cho tài liệu, dành riêng hoặc metadata của cloud sẽ bị từ chối khi bạn tạo webhook, và mọi địa chỉ IPv6 bọc một địa chỉ IPv4 (::ffff:…) cũng vậy. Ở mỗi lần gửi, tên host sẽ được phân giải: nếu bất kỳ địa chỉ nào của nó nằm trong các dải đó, sẽ không có gì được gửi và lần thử đó tính là thất bại. - Chuyển hướng (redirect) không được theo, và mỗi lần thử chờ phản hồi tối đa 5 giây. Hãy trả lời nhanh bằng một
2xxrồi xử lý công việc sau.
Sự kiện
| type | data | Được gửi khi |
|---|---|---|
session.started | { id, kind: "cdp" | "run", worker } | Một trình duyệt đã khởi động. kind là "cdp" với phiên do bạn điều khiển, "run" với một lượt chạy agent. |
session.ended | { id, kind, reason, usage: { bytesUp, bytesDown, seconds }, costEur } | Một phiên đã kết thúc, kèm lý do và những gì nó đã dùng. costEur là một con số duy nhất: với một lượt chạy thì là trình duyệt và agent cộng lại. Một phiên lost không bao giờ báo lại sẽ gửi sự kiện này khi bị kết thúc hẳn, với lý do worker_silent, hoặc worker_restarted khi server của nó hoạt động trở lại sau khi khởi động lại. |
run.finished | { id, status, result: { status, detail, url, title, output, outputError }, costEur } | Một lượt chạy agent đã kết thúc. status là succeeded, failed hoặc cancelled; result là phần chính trong kết quả của nó, hoặc null nếu nó không để lại kết quả nào; costEur là { browser, agent, total }. |
handoff.requested | { id, kind, reason, liveUrl, expiresAt } | Một trình duyệt đã được bàn giao cho một người. Hãy gửi liveUrl cho người cần thao tác. |
handoff.done | { id, kind } | Người đó đã nhấn “I'm done”, hoặc bạn đã đánh dấu là xong (qua API hoặc dashboard). Không được gửi khi một lần bàn giao hết hạn. |
recording.ready | { id, bytes, durationSec } | Một bản ghi hình đã sẵn sàng để tải xuống. |
ping | {} | Được gửi bởi lệnh gọi thử, để kiểm tra endpoint của bạn. |
id trong data là id của phiên hoặc của lượt chạy (chúng là một). Hãy lấy toàn bộ trạng thái bằng GET /api/v1/runs/<id> hoặc GET /api/v1/browsers/<id> khi bạn cần nhiều hơn những gì sự kiện mang theo. Một lượt chạy đang trong hàng đợi bị hủy hoặc hết hạn trước khi một server nhận nó sẽ không gửi session.ended lẫn run.finished.
Một lần gửi trông như thế nào
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": … }
}
}Gửi lại
Một lần gửi được tính khi server của bạn trả lời bằng một 2xx. Mọi trường hợp khác (một mã trạng thái khác, một redirect, một timeout, một kết nối bị từ chối) sẽ được thử lại. Tổng cộng có 6 lần thử: ngay lập tức, rồi khoảng 30 giây, 2 phút, 10 phút, 1 giờ và 6 giờ sau sự kiện. Sau lần thứ sáu, lần gửi được đánh dấu là thất bại và lastDelivery hiển thị điều đó. Ping thử chỉ được gửi một lần và không bao giờ thử lại.
- Hãy tính đến bản trùng lặp. Một lần gửi có thể đến nhiều hơn một lần, ví dụ khi phản hồi của bạn bị thất lạc.
Clearcote-Webhook-Id(idcủa phong bì) giống nhau ở mọi lần thử: hãy bỏ qua những id bạn đã xử lý. - Đừng dựa vào thứ tự. Một sự kiện được gửi lại có thể đến sau một sự kiện mới hơn. Hãy dùng
createdAt, hoặc lấy trạng thái hiện tại.
Kiểm tra chữ ký
Mọi lần gửi đều được ký bằng secret của webhook:
Clearcote-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the secret as key>Để kiểm tra, hãy tính cùng HMAC đó trên phần thân request thô (đúng từng byte, trước mọi bước parse JSON), so sánh nó với v1 theo thời gian hằng (constant time), và từ chối một t lệch quá 5 phút so với hiện tại, để một lần gửi cũ không thể bị phát lại. SDK làm tất cả những việc đó trong một lệnh gọi:
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) (cũng import được từ clearcote) trả về sự kiện đã parse và ném ValueError khi header bị thiếu hoặc sai định dạng, chữ ký không khớp, hoặc t nằm ngoài khoảng cho phép. Trong Node, verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) làm điều tương tự, một cách đồng bộ, và ném ra một Error. raw_body có thể là bytes hoặc string, toàn bộ chuỗi whsec_… chính là khóa, và chỉ cần một trong nhiều giá trị v1 khớp là đủ. Secret bị thiếu hoặc rỗng cũng gây lỗi, nên một biến môi trường chưa được đặt sẽ không bao giờ để lọt một lần gửi. Truyền tolerance_sec=None (Node: null) để bỏ qua bước kiểm tra thời gian, ví dụ khi phát lại một lần gửi đã lưu.
Với bất kỳ ngôn ngữ nào
Không cần SDK: đây là một HMAC-SHA256 thông thường với toàn bộ chuỗi secret (gồm cả whsec_) làm khóa. Trong Python, chỉ với thư viện chuẩn:
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)Và để tự kiểm tra một lần gửi đã lưu:
# 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