Transferência e webhooks
Algumas etapas precisam de uma pessoa: um CAPTCHA, um código enviado para um celular, um consentimento que só o titular da conta pode dar. A transferência passa um navegador em execução para uma pessoa por meio de um link e o pega de volta quando ela termina, tanto em sessões que você controla quanto em execuções de agente. Os webhooks avisam o seu servidor quando algo acontece, assinados para que você possa verificar que vieram de nós.
Transferência para uma pessoa
POST /api/v1/browsers/<id>/handoff numa sessão em execução retorna um link ao vivo. Quem abrir o link vê o navegador e pode clicar, digitar e rolar nele, sem precisar de conta. Quando termina, a pessoa clica em I'm done nessa página, e o seu código continua no mesmo navegador, com tudo o que ela fez (uma verificação concluída, uma conta logada) já no lugar.
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(opcional, até 500 caracteres numa linha) é uma nota para você e para o seu handler de webhooks: ela aparece na resposta, na visualização da sessão, no painel e no webhookhandoff.requested. A página que a pessoa abre mostra uma mensagem padrão (“assuma o controle e depois clique em I'm done”), então diga o que fazer quando enviar o link.timeoutSecé um número inteiro de 60 a 3600, padrão 600: o link funciona atéexpiresAt.- O token fica depois do
#naliveUrl, então nunca chega a um log de servidor. Repasse o link inteiro. - A sessão precisa estar em execução; caso contrário, a resposta é
409 NOT_RUNNING. Um navegador num servidor mais antigo responde409 HANDOFF_UNSUPPORTED; inicie uma nova sessão. Pedir de novo enquanto uma transferência aguarda retorna essa mesma transferência, com link, motivo eexpiresAtinalterados. - Marcar como concluída duas vezes dá a mesma resposta. É
409 NO_HANDOFFse nenhuma foi pedida, e409 HANDOFF_EXPIREDse ela expirou antes. - Enquanto uma transferência aguarda, a sessão não é fechada por inatividade, mesmo que nem o seu script nem a pessoa façam nada. O
timeoutSecda própria sessão (definido quando você a criou), omaxGbe o seu saldo continuam valendo. Quando a transferência é concluída ou expira, o timeout de inatividade volta a contar a partir desse momento. - O link é um link de controle: qualquer pessoa que o tenha pode controlar o navegador até ele expirar, logada como quem estiver logado no navegador. Envie-o só para a pessoa que deve agir.
- Um webhook
handoff.requestedtraz a mesmaliveUrl, então um handler de webhooks pode repassar o link (para um chat, um e-mail, um ticket) sem que o seu script precise fazer isso.
GET /api/v1/browsers/<id> mostra a transferência. handoff é null até você pedir uma, e liveUrl é null, a menos que state seja waiting. Depois que expiresAt passa sem “I'm done”, ou se a sessão terminou antes, state passa a ser timeout e o link para de funcionar. Uma sessão que você controla continua em execução; uma execução de agente termina (veja abaixo).
"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=…"
}A partir de um script
O seu script continua conectado durante uma transferência. Espere até a pessoa terminar e depois continue:
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 consulta GET /api/v1/browsers/<id> a cada 2 segundos até que handoff.state deixe de ser waiting, e retorna essa visualização da sessão. Passe um timeout (em segundos) para parar de esperar antes: nesse caso ele lança CloudTimeoutError e a transferência continua aberta. Para encerrar uma transferência do seu lado em vez de pelo botão, chame cloud.browsers.handoff_done(id) (Node: handoffDone(id)). Sem o SDK, consulte GET /api/v1/browsers/<id> a cada poucos segundos até que handoff.state seja done (ou timeout), ou espere o webhook handoff.done. Nenhum webhook é enviado quando uma transferência expira, então pare de esperar também ao chegar em expiresAt.
Em execuções de agente
Crie a execução com handoff: true. Quando o Jet para porque precisa de algo que não tem (needs_input) ou não consegue avançar (blocked), a execução não termina: ela pausa como waiting_for_human, o handoff da execução contém a liveUrl e um webhook handoff.requested é enviado.
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}'- Quando a pessoa clica em “I'm done”, o Jet recomeça na mesma página com a mesma tarefa e vê a página como ela a deixou (se ela fechou essa aba, ele recomeça na
urlda execução). - Uma execução pode ser transferida até três vezes.
result.handoffsconta as transferências, e as etapas de antes e de depois estão todas emresult.steps. handoffTimeoutSec(de 60 a 3600, padrão 600) é quanto tempo cada transferência espera. Se ninguém terminar a tempo, a execução termina com o status em que o Jet parou, ou seja,failed. OtimeoutSecda própria execução (padrão 900) continua contando durante uma transferência: aumente-o quando aumentarhandoffTimeoutSec.- Use com um
profileepersist: true: os logins que a pessoa fizer ficam salvos, e a próxima execução não precisa mais dela.
Webhooks
Um webhook é uma URL sua para a qual enviamos um POST assinado quando algo acontece. Crie um pela API, pelo SDK, pela CLI ou pelas configurações do painel:
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
# }O secret só aparece na resposta da criação; é com ele que você verifica as assinaturas. Perdeu? Exclua o webhook e crie um novo.
# 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 até algo ser enviado. O status dele, e o status de um teste, é o status HTTP com que o seu servidor respondeu, ou null quando não houve resposta; um teste que falhou também tem um error dizendo o motivo. Um ping de teste é enviado mesmo quando events não inclui ping.
Regras
- No máximo 5 webhooks por conta; um sexto retorna
409 WEBHOOK_LIMIT.descriptiontem até 200 caracteres numa linha. eventsescolhe o que é enviado (tabela abaixo). Omita, ou envie uma lista vazia, para receber tudo excetoping.- A URL precisa ser
https://, ter no máximo 2048 caracteres, não ter nome de usuário nem senha e estar na internet pública.localhost, nomes de um único rótulo (comohttps://intranet) e endereços IP em faixas privadas, de loopback, link-local, NAT de nível de operadora (CGNAT), multicast, de documentação, reservadas ou de metadados de nuvem são recusados quando você cria o webhook, assim como qualquer endereço IPv6 que encapsule um IPv4 (::ffff:…). A cada entrega, o nome do host é resolvido: se algum dos endereços dele estiver nessas faixas, nada é enviado e a tentativa conta como falha. - Redirecionamentos não são seguidos, e cada tentativa espera no máximo 5 segundos por uma resposta. Responda rápido com um
2xxe faça o trabalho depois.
Eventos
| type | data | Enviado quando |
|---|---|---|
session.started | { id, kind: "cdp" | "run", worker } | Um navegador foi iniciado. kind é "cdp" para uma sessão que você controla e "run" para uma execução de agente. |
session.ended | { id, kind, reason, usage: { bytesUp, bytesDown, seconds }, costEur } | Uma sessão terminou, com o motivo e o que ela consumiu. costEur é um único número: navegador e agente somados, no caso de uma execução. Uma sessão lost que nunca mais se reporta envia este evento quando é encerrada de vez, com o motivo worker_silent, ou worker_restarted quando o servidor dela volta depois de uma reinicialização. |
run.finished | { id, status, result: { status, detail, url, title, output, outputError }, costEur } | Uma execução de agente terminou. status é succeeded, failed ou cancelled; result é a parte principal do resultado, ou null se ela não deixou nenhum; costEur é { browser, agent, total }. |
handoff.requested | { id, kind, reason, liveUrl, expiresAt } | Um navegador foi passado para uma pessoa. Envie a liveUrl para quem deve agir. |
handoff.done | { id, kind } | A pessoa clicou em “I'm done”, ou você marcou como concluída (API ou painel). Não é enviado quando uma transferência expira. |
recording.ready | { id, bytes, durationSec } | Uma gravação está pronta para download. |
ping | {} | Enviado pela chamada de teste, para verificar o seu endpoint. |
id em data é o id da sessão ou da execução (são a mesma coisa). Busque o estado completo com GET /api/v1/runs/<id> ou GET /api/v1/browsers/<id> quando precisar de mais do que o evento traz. Uma execução na fila que é cancelada ou expira antes de um servidor pegá-la não envia nem session.ended nem run.finished.
Como é uma entrega
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": … }
}
}Novas tentativas
Uma entrega conta quando o seu servidor responde com um 2xx. Qualquer outra coisa (outro status, um redirecionamento, um timeout, uma conexão recusada) é tentada de novo. São 6 tentativas no total: imediatamente e depois cerca de 30 segundos, 2 minutos, 10 minutos, 1 hora e 6 horas após o evento. Depois da sexta, a entrega é marcada como falha e o lastDelivery mostra isso. Um ping de teste é enviado uma vez e nunca é repetido.
- Conte com duplicatas. Uma entrega pode chegar mais de uma vez, por exemplo quando a sua resposta se perdeu.
Clearcote-Webhook-Id(oiddo envelope) é o mesmo em todas as tentativas: pule os ids que você já processou. - Não dependa da ordem. Um evento repetido pode chegar depois de um mais recente. Use
createdAt, ou busque o estado atual.
Verificar assinaturas
Toda entrega é assinada com o secret do seu webhook:
Clearcote-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the secret as key>Para verificar uma, calcule o mesmo HMAC sobre o corpo bruto da requisição (os bytes exatos, antes de qualquer parsing de JSON), compare com v1 em tempo constante e rejeite um t a mais de 5 minutos de agora, para que uma entrega antiga não possa ser reenviada. O SDK faz tudo isso numa única chamada:
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) (também pode ser importado de clearcote) retorna o evento já parseado e lança ValueError quando o header está ausente ou malformado, a assinatura não confere ou t está fora do intervalo. No Node, verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) faz o mesmo, de forma síncrona, e lança um Error. raw_body pode ser bytes ou uma string, a string whsec_… inteira é a chave, e basta que um de vários valores v1 confira. Um secret ausente ou vazio também gera um erro, então uma variável de ambiente não definida nunca deixa uma entrega passar. Passe tolerance_sec=None (Node: null) para pular a verificação de tempo, por exemplo ao reenviar uma entrega salva.
Em qualquer linguagem
Não precisa do SDK: é um HMAC-SHA256 comum, com a string inteira do secret (whsec_ incluído) como chave. Em Python, só com a biblioteca padrão:
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)E para verificar uma entrega salva manualmente:
# 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