引き継ぎと Webhook
人の手が必要なステップもあります。CAPTCHA、電話に届くコード、アカウントの所有者しか行えない同意などです。引き継ぎは、実行中のブラウザをリンク経由で人に渡し、その人の作業が終わったら取り戻します。あなたが操作するセッションでも、エージェントの実行でも使えます。Webhook は何かが起きたときにあなたのサーバーへ通知します。署名付きなので、Clearcote から送られたものか確認できます。
人への引き継ぎ
実行中のセッションに 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(省略可、1 行で 500 文字まで)は、あなたと Webhook ハンドラー向けのメモです。レスポンス、セッションビュー、ダッシュボード、handoff.requestedWebhook に含まれます。相手が開くページには「操作を引き継ぎ、終わったら I'm done を押す」という定型メッセージが表示されるだけなので、リンクを送るときに何をしてほしいかを伝えてください。timeoutSecは 60 から 3600 までの整数で、既定値は 600 です。リンクはexpiresAtまで有効です。- トークンは
liveUrlの#の後ろにあるため、サーバーログに残ることはありません。リンクは丸ごと渡してください。 - セッションは実行中である必要があり、そうでなければ
409 NOT_RUNNINGが返ります。古いサーバー上のブラウザは409 HANDOFF_UNSUPPORTEDを返すので、新しいセッションを開始してください。引き継ぎの待機中にもう一度リクエストすると、同じ引き継ぎが返り、リンク、理由、expiresAtは変わりません。 - 完了を 2 回送っても同じレスポンスが返ります。引き継ぎを要求していなければ
409 NO_HANDOFF、先にタイムアウトしていれば409 HANDOFF_EXPIREDです。 - 引き継ぎの待機中は、スクリプトも相手も何もしていなくても、セッションがアイドルとして閉じられることはありません。ただし、セッション自体の
timeoutSec(作成時に指定したもの)、maxGb、残高は引き続き適用されます。引き継ぎが完了するかタイムアウトすると、アイドルタイムアウトはその時点から改めてカウントされます。 - このリンクは操作用のリンクです。持っている人は誰でも、期限が切れるまで、ブラウザがサインインしているアカウントのままでブラウザを操作できます。対応すべき人にだけ送ってください。
handoff.requestedWebhook にも同じliveUrlが含まれるので、スクリプトで処理しなくても、Webhook ハンドラーからリンクを(チャット、メール、チケットなどに)転送できます。
GET /api/v1/browsers/<id> で引き継ぎの状態を確認できます。handoff は引き継ぎを要求するまで null で、liveUrl は state が waiting のとき以外は null です。「I'm done」が押されないまま expiresAt を過ぎるか、その前にセッションが終了すると、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 は、handoff.state が waiting でなくなるまで 2 秒ごとに GET /api/v1/browsers/<id> をポーリングし、そのセッションビューを返します。timeout(秒)を指定すると、それより早く待機を打ち切ります。その場合は CloudTimeoutError が発生し、引き継ぎは開いたままです。ボタンではなくあなたの側から引き継ぎを終えるには、cloud.browsers.handoff_done(id)(Node では handoffDone(id))を呼び出します。SDK を使わない場合は、handoff.state が done(または timeout)になるまで数秒ごとに GET /api/v1/browsers/<id> をポーリングするか、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からやり直します)。 - 1 回の実行で引き継ぎは 3 回までできます。
result.handoffsがその回数で、引き継ぎ前後のステップはすべてresult.stepsに入ります。 handoffTimeoutSec(60 から 3600、既定値 600)は、各引き継ぎの待機時間です。時間内に誰も終えなければ、実行は Jet が止まったときのステータスで終了するため、failedになります。実行自体のtimeoutSec(既定値 900)は引き継ぎ中もカウントされ続けるので、handoffTimeoutSecを増やすときはこちらも増やしてください。profileとpersist: trueと組み合わせて使ってください。相手がサインインした状態が保存され、次回の実行ではその人の手が不要になります。
Webhook
Webhook とは、何かが起きたときに Clearcote が署名付きの POST を送る、あなたの URL です。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 も含まれます。テスト ping は、events に ping が含まれていなくても送られます。
ルール
- Webhook は 1 アカウントあたり最大 5 個で、6 個目は
409 WEBHOOK_LIMITになります。descriptionは 1 行で 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 は 1 つの数値で、実行の場合はブラウザとエージェントの合計です。二度と応答しない 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 です(この 2 つは同じものです)。イベントに含まれる以上の情報が必要な場合は、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 回で、すぐに 1 回、その後イベントから約 30 秒後、2 分後、10 分後、1 時間後、6 時間後です。6 回目の後、配信は失敗として記録され、lastDelivery にそれが表示されます。テスト ping は 1 回だけ送られ、リトライされません。
- 重複を想定してください。たとえばあなたの応答が失われた場合など、同じ配信が複数回届くことがあります。
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 なら、これを 1 回の呼び出しで行えます。
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 値のうち 1 つが一致すれば十分です。シークレットがない、または空の場合もエラーになるため、環境変数が未設定でも配信が素通りすることはありません。保存した配信をリプレイするときなど、時刻チェックを省くには tolerance_sec=None(Node では null)を渡します。
どの言語でも
SDK は必須ではありません。シークレット文字列全体(whsec_ を含む)を鍵とした、ごく普通の HMAC-SHA256 です。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