Passage de relais et webhooks
Certaines étapes demandent une personne : un CAPTCHA, un code envoyé sur un téléphone, un consentement que seul le titulaire du compte peut donner. Le passage de relais confie un navigateur en cours d’exécution à une personne via un lien, puis le reprend quand elle a terminé, pour les sessions que vous pilotez comme pour les exécutions d’agent. Les webhooks préviennent votre serveur quand quelque chose se produit, et sont signés pour que vous puissiez vérifier qu’ils viennent bien de nous.
Passer la main à une personne
POST /api/v1/browsers/<id>/handoff sur une session en cours renvoie un lien en direct. La personne qui l’ouvre voit le navigateur et peut y cliquer, taper et faire défiler, sans compte. Quand elle a fini, elle appuie sur I'm done sur cette page, et votre code reprend dans le même navigateur, avec tout ce qu’elle a fait (une vérification réussie, un compte connecté) déjà en place.
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(facultatif, jusqu’à 500 caractères sur une ligne) est une note pour vous et votre handler de webhooks : elle figure dans la réponse, la vue de la session, le tableau de bord et le webhookhandoff.requested. La page que la personne ouvre affiche un message standard (« prenez la main, puis appuyez sur I'm done »), alors dites-lui quoi faire en lui envoyant le lien.timeoutSecest un entier de 60 à 3600, 600 par défaut : le lien fonctionne jusqu’àexpiresAt.- Le jeton se trouve après le
#dansliveUrl, il n’atteint donc jamais un log de serveur. Transmettez le lien en entier. - La session doit être en cours d’exécution, sinon la réponse est
409 NOT_RUNNING. Un navigateur sur un serveur plus ancien répond409 HANDOFF_UNSUPPORTED; démarrez une nouvelle session. Redemander pendant qu’un passage de relais attend renvoie ce même passage de relais, avec son lien, sa raison et sonexpiresAtinchangés. - Le marquer comme terminé deux fois donne la même réponse. C’est
409 NO_HANDOFFsi aucun n’a été demandé, et409 HANDOFF_EXPIREDs’il a expiré avant. - Tant qu’un passage de relais attend, la session n’est pas fermée pour inactivité, même si ni votre script ni la personne ne font quoi que ce soit. Le
timeoutSecpropre à la session (défini à sa création),maxGbet votre solde s’appliquent toujours. Une fois le passage de relais terminé ou expiré, le délai d’inactivité repart de ce moment-là. - Le lien est un lien de contrôle : toute personne qui l’a peut piloter le navigateur jusqu’à son expiration, connectée sous l’identité avec laquelle le navigateur est connecté. Ne l’envoyez qu’à la personne qui doit agir.
- Un webhook
handoff.requestedcontient le mêmeliveUrl, si bien qu’un handler de webhooks peut transmettre le lien (dans un chat, un e-mail, un ticket) sans que votre script s’en charge.
GET /api/v1/browsers/<id> affiche le passage de relais. handoff vaut null tant que vous n’en avez pas demandé, et liveUrl vaut null sauf si state vaut waiting. Une fois expiresAt passé sans « I'm done », ou si la session s’est terminée avant, state vaut timeout et le lien cesse de fonctionner. Une session que vous pilotez continue de tourner ; une exécution d’agent se termine (voir plus bas).
"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=…"
}Depuis un script
Votre script reste connecté pendant un passage de relais. Attendez que la personne ait terminé, puis continuez :
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 interroge GET /api/v1/browsers/<id> toutes les 2 secondes jusqu’à ce que handoff.state ne soit plus waiting, et renvoie cette vue de la session. Passez-lui un timeout (en secondes) pour arrêter d’attendre plus tôt : il lève alors CloudTimeoutError et le passage de relais reste ouvert. Pour terminer un passage de relais de votre côté plutôt qu’avec le bouton, appelez cloud.browsers.handoff_done(id) (Node : handoffDone(id)). Sans le SDK, interrogez GET /api/v1/browsers/<id> toutes les quelques secondes jusqu’à ce que handoff.state vaille done (ou timeout), ou attendez le webhook handoff.done. Aucun webhook n’est envoyé quand un passage de relais expire : arrêtez donc aussi d’attendre à expiresAt.
Dans les exécutions d’agent
Créez l’exécution avec handoff: true. Quand Jet s’arrête parce qu’il lui manque quelque chose (needs_input) ou qu’il ne peut pas aller plus loin (blocked), l’exécution ne se termine pas : elle se met en pause en waiting_for_human, le handoff de l’exécution contient le liveUrl, et un webhook handoff.requested est envoyé.
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}'- Quand la personne appuie sur « I'm done », Jet repart sur la même page avec la même tâche, et voit la page telle qu’elle l’a laissée (si elle a fermé cet onglet, il repart de l’
urlde l’exécution). - Une exécution peut passer la main jusqu’à trois fois.
result.handoffsles compte, et les étapes d’avant et d’après se trouvent toutes dansresult.steps. handoffTimeoutSec(de 60 à 3600, 600 par défaut) est la durée d’attente de chaque passage de relais. Si personne n’a fini à temps, l’exécution se termine avec le statut sur lequel Jet s’est arrêté, doncfailed. LetimeoutSecpropre à l’exécution (900 par défaut) continue de courir pendant un passage de relais : augmentez-le quand vous augmentezhandoffTimeoutSec.- Utilisez-le avec un
profileetpersist: true: les connexions faites par la personne sont enregistrées, et l’exécution suivante n’a plus besoin d’elle.
Webhooks
Un webhook est une URL à vous à laquelle nous envoyons un POST signé quand quelque chose se produit. Créez-en un avec l’API, le SDK, la CLI ou les paramètres du tableau de bord :
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
# }Le secret ne figure que dans la réponse de création ; c’est avec lui que vous vérifiez les signatures. Vous l’avez perdu ? Supprimez le webhook et créez-en un nouveau.
# 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 vaut null tant que rien n’a été envoyé. Son status, comme le status d’un test, est le statut HTTP renvoyé par votre serveur, ou null en l’absence de réponse ; un test en échec contient aussi un error qui en donne la raison. Un ping de test est envoyé même quand events ne contient pas ping.
Règles
- 5 webhooks au maximum par compte ; un sixième renvoie
409 WEBHOOK_LIMIT.descriptionfait au plus 200 caractères sur une ligne. eventschoisit ce qui est envoyé (tableau ci-dessous). Omettez-le, ou envoyez une liste vide, pour tout recevoir saufping.- L’URL doit être en
https://, faire au plus 2048 caractères, ne contenir ni nom d’utilisateur ni mot de passe, et être sur l’internet public.localhost, les noms à un seul label (commehttps://intranet) et les adresses IP des plages privées, loopback, link-local, NAT de niveau opérateur (CGNAT), multicast, de documentation, réservées ou de métadonnées cloud sont refusés à la création du webhook, tout comme toute adresse IPv6 qui encapsule une adresse IPv4 (::ffff:…). À chaque livraison, le nom d’hôte est résolu : si l’une de ses adresses se trouve dans ces plages, rien n’est envoyé et la tentative compte comme un échec. - Les redirections ne sont pas suivies, et chaque tentative attend une réponse 5 secondes au plus. Répondez vite avec un
2xxet faites le travail ensuite.
Événements
| type | data | Envoyé quand |
|---|---|---|
session.started | { id, kind: "cdp" | "run", worker } | Un navigateur a démarré. kind vaut "cdp" pour une session que vous pilotez, "run" pour une exécution d’agent. |
session.ended | { id, kind, reason, usage: { bytesUp, bytesDown, seconds }, costEur } | Une session s’est terminée, avec la raison et ce qu’elle a consommé. costEur est un seul nombre : navigateur et agent ensemble pour une exécution. Une session lost qui ne se manifeste plus l’envoie quand elle est terminée pour de bon, avec la raison worker_silent, ou worker_restarted une fois son serveur revenu après un redémarrage. |
run.finished | { id, status, result: { status, detail, url, title, output, outputError }, costEur } | Une exécution d’agent s’est terminée. status vaut succeeded, failed ou cancelled ; result est la partie principale de son résultat, ou null si elle n’en a laissé aucun ; costEur vaut { browser, agent, total }. |
handoff.requested | { id, kind, reason, liveUrl, expiresAt } | Un navigateur a été confié à une personne. Envoyez liveUrl à la personne qui doit agir. |
handoff.done | { id, kind } | La personne a appuyé sur « I'm done », ou vous l’avez marqué comme terminé (API ou tableau de bord). Pas envoyé quand un passage de relais expire. |
recording.ready | { id, bytes, durationSec } | Un enregistrement peut être téléchargé. |
ping | {} | Envoyé par l’appel de test, pour vérifier votre endpoint. |
id dans data est l’id de la session ou de l’exécution (c’est la même chose). Récupérez l’état complet avec GET /api/v1/runs/<id> ou GET /api/v1/browsers/<id> quand il vous faut plus que ce que contient l’événement. Une exécution en file d’attente qui est annulée ou expire avant qu’un serveur ne la prenne n’envoie ni session.ended ni run.finished.
À quoi ressemble une livraison
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": … }
}
}Nouvelles tentatives
Une livraison compte quand votre serveur répond avec un 2xx. Tout le reste (un autre statut, une redirection, un timeout, une connexion refusée) est retenté. Il y a 6 tentatives en tout : immédiatement, puis environ 30 secondes, 2 minutes, 10 minutes, 1 heure et 6 heures après l’événement. Après la sixième, la livraison est marquée en échec et lastDelivery l’indique. Un ping de test est envoyé une fois et jamais retenté.
- Attendez-vous à des doublons. Une livraison peut arriver plus d’une fois, par exemple quand votre réponse s’est perdue.
Clearcote-Webhook-Id(l’idde l’enveloppe) est le même à chaque tentative : ignorez les ids que vous avez déjà traités. - Ne comptez pas sur l’ordre. Un événement retenté peut arriver après un événement plus récent. Utilisez
createdAt, ou récupérez l’état actuel.
Vérifier les signatures
Chaque livraison est signée avec le secret de votre webhook :
Clearcote-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the secret as key>Pour en vérifier une, calculez le même HMAC sur le corps brut de la requête (les octets exacts, avant tout parsing JSON), comparez-le à v1 en temps constant, et rejetez un t éloigné de plus de 5 minutes de l’heure actuelle, pour qu’une ancienne livraison ne puisse pas être rejouée. Le SDK fait tout cela en un seul appel :
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) (importable aussi depuis clearcote) renvoie l’événement parsé et lève ValueError quand l’en-tête est absent ou mal formé, que la signature ne correspond pas, ou que t est hors plage. En Node, verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) fait la même chose, de façon synchrone, et lève une Error. raw_body peut être des octets ou une chaîne, la chaîne whsec_… entière est la clé, et il suffit qu’une seule de plusieurs valeurs v1 corresponde. Un secret absent ou vide lève aussi une erreur, si bien qu’une variable d’environnement non définie ne laisse jamais passer une livraison. Passez tolerance_sec=None (Node : null) pour ignorer la vérification de l’heure, par exemple pour rejouer une livraison enregistrée.
Dans n’importe quel langage
Pas besoin du SDK : c’est un simple HMAC-SHA256 avec la chaîne complète du secret (whsec_ compris) comme clé. En Python, avec la seule bibliothèque standard :
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)Et pour vérifier à la main une livraison enregistrée :
# 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