Pular para o conteúdo

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.

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 (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 webhook handoff.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 # na liveUrl, 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 responde 409 HANDOFF_UNSUPPORTED; inicie uma nova sessão. Pedir de novo enquanto uma transferência aguarda retorna essa mesma transferência, com link, motivo e expiresAt inalterados.
  • Marcar como concluída duas vezes dá a mesma resposta. É 409 NO_HANDOFF se nenhuma foi pedida, e 409 HANDOFF_EXPIRED se 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 timeoutSec da própria sessão (definido quando você a criou), o maxGb e 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.requested traz a mesma liveUrl, 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).

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

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.

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}'
  • 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 url da execução).
  • Uma execução pode ser transferida até três vezes. result.handoffs conta as transferências, e as etapas de antes e de depois estão todas em result.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. O timeoutSec da própria execução (padrão 900) continua contando durante uma transferência: aumente-o quando aumentar handoffTimeoutSec.
  • Use com um profile e persist: 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.

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 é 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. description tem até 200 caracteres numa linha.
  • events escolhe o que é enviado (tabela abaixo). Omita, ou envie uma lista vazia, para receber tudo exceto ping.
  • 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 (como https://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 2xx e faça o trabalho depois.

Eventos

typedataEnviado 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

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

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 (o id do 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:

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

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

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)

E para verificar uma entrega salva manualmente:

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

Atualizado em 12 de out. de 2026 · SDK 0.70.5 · navegador r63

Esta página foi útil?