Saltar al contenido

Traspaso y webhooks

Algunos pasos necesitan a una persona: un CAPTCHA, un código enviado a un teléfono, un consentimiento que solo puede dar el titular de la cuenta. El traspaso entrega un navegador en ejecución a una persona mediante un enlace y lo recupera cuando termina, tanto en sesiones que controlas tú como en ejecuciones de agente. Los webhooks avisan a tu servidor cuando ocurre algo, firmados para que puedas comprobar que vienen de nosotros.

Traspaso a una persona

POST /api/v1/browsers/<id>/handoff sobre una sesión en ejecución devuelve un enlace en vivo. Quien lo abra ve el navegador y puede hacer clic, escribir y desplazarse en él, sin cuenta. Cuando termina, pulsa I'm done en esa página y tu código continúa en el mismo navegador, con todo lo que hizo esa persona (una verificación superada, una cuenta con la sesión iniciada) ya en su sitio.

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, hasta 500 caracteres en una sola línea) es una nota para ti y para tu handler de webhooks: aparece en la respuesta, en la vista de la sesión, en el panel y en el webhook handoff.requested. La página que abre la persona muestra un mensaje estándar (“toma el control y luego pulsa I'm done”), así que indica qué hay que hacer cuando envíes el enlace. timeoutSec es un número entero de 60 a 3600, 600 por defecto: el enlace funciona hasta expiresAt.
  • El token va después del # en liveUrl, así que nunca llega a un log de servidor. Pasa el enlace completo.
  • La sesión tiene que estar en ejecución; si no, la respuesta es 409 NOT_RUNNING. Un navegador en un servidor más antiguo responde 409 HANDOFF_UNSUPPORTED; inicia una sesión nueva. Si lo pides de nuevo mientras un traspaso está en espera, recibes ese mismo traspaso, con su enlace, su motivo y su expiresAt sin cambios.
  • Marcarlo como terminado dos veces da la misma respuesta. Es 409 NO_HANDOFF si no se pidió ninguno, y 409 HANDOFF_EXPIRED si expiró antes.
  • Mientras un traspaso está en espera, la sesión no se cierra por inactividad, aunque ni tu script ni la persona hagan nada. El timeoutSec propio de la sesión (el que definiste al crearla), maxGb y tu saldo siguen aplicándose. Cuando el traspaso termina o expira, el tiempo de inactividad vuelve a contar desde ese momento.
  • El enlace es un enlace de control: cualquiera que lo tenga puede manejar el navegador hasta que expire, con la sesión iniciada como la tenga el navegador. Envíalo solo a la persona que deba actuar.
  • Un webhook handoff.requested lleva el mismo liveUrl, así que un handler de webhooks puede pasar el enlace (a un chat, un correo, un ticket) sin que tu script tenga que hacerlo.

GET /api/v1/browsers/<id> muestra el traspaso. handoff es null hasta que pidas uno, y liveUrl es null salvo que state sea waiting. Cuando expiresAt ha pasado sin “I'm done”, o la sesión terminó antes, state indica timeout y el enlace deja de funcionar. Una sesión que controlas tú sigue en ejecución; una ejecución de agente termina (ver más abajo).

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

Desde un script

Tu script sigue conectado durante un traspaso. Espera a que la persona termine y luego continúa:

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> cada 2 segundos hasta que handoff.state deja de ser waiting, y devuelve esa vista de la sesión. Dale un timeout (en segundos) para que deje de esperar antes: entonces lanza CloudTimeoutError y el traspaso sigue abierto. Para terminar un traspaso desde tu lado en lugar de con el botón, llama a cloud.browsers.handoff_done(id) (Node: handoffDone(id)). Sin el SDK, consulta GET /api/v1/browsers/<id> cada pocos segundos hasta que handoff.state sea done (o timeout), o espera el webhook handoff.done. Cuando un traspaso expira no se envía ningún webhook, así que deja de esperar también al llegar a expiresAt.

En ejecuciones de agente

Crea la ejecución con handoff: true. Cuando Jet se detiene porque necesita algo que no tiene (needs_input) o no puede avanzar más (blocked), la ejecución no termina: se pausa como waiting_for_human, el handoff de la ejecución contiene el liveUrl y se envía un webhook handoff.requested.

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}'
  • Cuando la persona pulsa “I'm done”, Jet vuelve a empezar en la misma página con la misma tarea y ve la página tal como la dejó (si cerró esa pestaña, empieza de nuevo en la url de la ejecución).
  • Una ejecución puede traspasarse hasta tres veces. result.handoffs los cuenta, y los pasos de antes y de después están todos en result.steps.
  • handoffTimeoutSec (de 60 a 3600, 600 por defecto) es cuánto espera cada traspaso. Si nadie termina a tiempo, la ejecución termina con el estado en el que se detuvo Jet, así que es failed. El timeoutSec propio de la ejecución (900 por defecto) sigue contando durante un traspaso: súbelo cuando subas handoffTimeoutSec.
  • Úsalo con un profile y persist: true: los inicios de sesión que haga la persona se guardan, y la siguiente ejecución ya no la necesita.

Webhooks

Un webhook es una URL tuya a la que enviamos un POST firmado cuando ocurre algo. Créalo con la API, el SDK, la CLI o la configuración del panel:

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
# }

El secret solo aparece en la respuesta de creación; es con lo que compruebas las firmas. ¿Lo perdiste? Elimina el webhook y crea uno nuevo.

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 es null hasta que se haya enviado algo. Su status, y el status de una prueba, es el código HTTP con el que respondió tu servidor, o null cuando no hubo respuesta; una prueba fallida también trae un error que dice por qué. Se envía un ping de prueba aunque events no incluya ping.

Reglas

  • Como máximo 5 webhooks por cuenta; un sexto devuelve 409 WEBHOOK_LIMIT. description admite hasta 200 caracteres en una sola línea.
  • events elige qué se envía (tabla de abajo). Omítelo, o envía una lista vacía, para recibir todo excepto ping.
  • La URL debe ser https://, tener como máximo 2048 caracteres, no llevar usuario ni contraseña y estar en internet pública. localhost, los nombres de una sola etiqueta (como https://intranet) y las direcciones IP en rangos privados, de loopback, link-local, NAT de nivel de operador (CGNAT), multicast, de documentación, reservados o de metadatos de la nube se rechazan al crear el webhook, igual que cualquier dirección IPv6 que envuelva una IPv4 (::ffff:…). En cada entrega se resuelve el nombre de host: si alguna de sus direcciones está en esos rangos, no se envía nada y el intento cuenta como fallido.
  • No se siguen redirecciones, y cada intento espera como máximo 5 segundos una respuesta. Responde rápido con un 2xx y haz el trabajo después.

Eventos

typedataSe envía cuando
session.started{ id, kind: "cdp" | "run", worker }Se inició un navegador. kind es "cdp" para una sesión que controlas tú y "run" para una ejecución de agente.
session.ended{ id, kind, reason, usage: { bytesUp, bytesDown, seconds }, costEur }Una sesión terminó, con el motivo y lo que consumió. costEur es un solo número: en una ejecución, navegador y agente juntos. Una sesión lost que no vuelve a reportarse lo envía cuando se da por terminada definitivamente, con el motivo worker_silent, o worker_restarted cuando su servidor vuelve tras un reinicio.
run.finished{ id, status, result: { status, detail, url, title, output, outputError }, costEur }Una ejecución de agente terminó. status es succeeded, failed o cancelled; result es la parte principal de su resultado, o null si no dejó ninguno; costEur es { browser, agent, total }.
handoff.requested{ id, kind, reason, liveUrl, expiresAt }Se entregó un navegador a una persona. Envía liveUrl a quien deba actuar.
handoff.done{ id, kind }La persona pulsó “I'm done”, o tú lo marcaste como terminado (API o panel). No se envía cuando un traspaso expira.
recording.ready{ id, bytes, durationSec }Una grabación está lista para descargar.
ping{}Lo envía la llamada de prueba, para comprobar tu endpoint.

id en data es el id de la sesión o de la ejecución (son lo mismo). Obtén el estado completo con GET /api/v1/runs/<id> o GET /api/v1/browsers/<id> cuando necesites más de lo que trae el evento. Una ejecución en cola que se cancela o expira antes de que un servidor la tome no envía ni session.ended ni run.finished.

Cómo es una 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": … }
  }
}

Reintentos

Una entrega cuenta cuando tu servidor responde con un 2xx. Cualquier otra cosa (otro código, una redirección, un timeout, una conexión rechazada) se vuelve a intentar. Hay 6 intentos en total: de inmediato y luego unos 30 segundos, 2 minutos, 10 minutos, 1 hora y 6 horas después del evento. Tras el sexto, la entrega se marca como fallida y lastDelivery lo muestra. Un ping de prueba se envía una vez y nunca se reintenta.

  • Cuenta con duplicados. Una entrega puede llegar más de una vez, por ejemplo cuando tu respuesta se perdió. Clearcote-Webhook-Id (el id del sobre) es el mismo en cada intento: omite los ids que ya procesaste.
  • No dependas del orden. Un evento reintentado puede llegar después de uno posterior. Usa createdAt, u obtén el estado actual.

Verificar firmas

Cada entrega va firmada con el secreto de tu webhook:

text
Clearcote-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the secret as key>

Para comprobar una, calcula el mismo HMAC sobre el cuerpo de la solicitud sin procesar (los bytes exactos, antes de cualquier parseo de JSON), compáralo con v1 en tiempo constante y rechaza un t que se aleje más de 5 minutos de ahora, para que no se pueda reproducir una entrega antigua. El SDK hace todo eso en una sola llamada:

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) (también se puede importar desde clearcote) devuelve el evento ya parseado y lanza ValueError cuando falta el header o está mal formado, la firma no coincide o t está fuera de rango. En Node, verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) hace lo mismo, de forma síncrona, y lanza un Error. raw_body puede ser bytes o un string, la cadena whsec_… completa es la clave, y basta con que coincida uno de varios valores v1. Un secreto ausente o vacío también lanza un error, así que una variable de entorno sin definir nunca deja pasar una entrega. Pasa tolerance_sec=None (Node: null) para omitir la comprobación de tiempo, por ejemplo al reproducir una entrega guardada.

En cualquier lenguaje

No hace falta el SDK: es un HMAC-SHA256 normal con la cadena completa del secreto (whsec_ incluido) como clave. En Python, solo con la biblioteca estándar:

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)

Y para comprobar a mano una entrega guardada:

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

Actualizado el 12 oct 2026 · SDK 0.70.5 · navegador r63

¿Te resultó útil esta página?