Chuyển đến nội dung

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.

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 (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 webhook handoff.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. timeoutSec là số nguyên từ 60 đến 3600, mặc định 600: liên kết hoạt động đến expiresAt.
  • Token nằm sau dấu # trong liveUrl, 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à expiresAt khô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_HANDOFF nếu chưa có yêu cầu bàn giao nào, và 409 HANDOFF_EXPIRED nế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ì. timeoutSec riêng của phiên (đặt khi bạn tạo phiên), maxGb và 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.requested mang cùng liveUrl, 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).

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=…"
}

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.

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}'
  • 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 ở url củ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 trong result.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. timeoutSec riê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ăng handoffTimeoutSec.
  • Dùng nó cùng một profile và 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.

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 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. description dài tối đa 200 ký tự trên một dòng.
  • events chọ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 2xx rồi xử lý công việc sau.

Sự kiện

typedataĐượ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

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": … }
  }
}

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 (id củ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:

text
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 "", 204

verify_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:

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)

Và để tự kiểm tra một lần gửi đã lưu:

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

Cập nhật 12 thg 10, 2026 · SDK 0.70.5 · trình duyệt r63

Trang này có hữu ích không?