Zum Inhalt springen

Übergabe und Webhooks

Manche Schritte brauchen einen Menschen: ein CAPTCHA, ein an ein Telefon gesendeter Code, eine Zustimmung, die nur der Kontoinhaber geben kann. Übergabe gibt einen laufenden Browser über einen Link an einen Menschen und holt ihn zurück, sobald dieser fertig ist, für Sessions, die Sie selbst steuern, und für Agent-Runs. Webhooks melden Ihrem Server, wenn etwas passiert, und sind signiert, damit Sie prüfen können, dass sie von uns kommen.

Übergabe an einen Menschen

POST /api/v1/browsers/<id>/handoff auf eine laufende Session liefert einen Live-Link. Wer ihn öffnet, sieht den Browser und kann darin klicken, tippen und scrollen, ganz ohne Account. Ist die Person fertig, drückt sie auf dieser Seite I'm done, und Ihr Code macht im selben Browser weiter, mit allem, was sie getan hat (eine bestandene Prüfung, ein angemeldeter Account), an Ort und Stelle.

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 (optional, bis zu 500 Zeichen in einer Zeile) ist eine Notiz für Sie und Ihren Webhook-Handler: Sie steht in der Antwort, in der Session-Ansicht, im Dashboard und im handoff.requested-Webhook. Die Seite, die die Person öffnet, zeigt eine Standardnachricht („übernehmen, dann I'm done drücken“). Sagen Sie also beim Senden des Links, was zu tun ist. timeoutSec ist eine ganze Zahl von 60 bis 3600, Standard 600: Der Link funktioniert bis expiresAt.
  • Das Token steht nach dem # in liveUrl und landet deshalb nie in einem Server-Log. Geben Sie den Link vollständig weiter.
  • Die Session muss laufen, sonst lautet die Antwort 409 NOT_RUNNING. Ein Browser auf einem älteren Server antwortet mit 409 HANDOFF_UNSUPPORTED; starten Sie eine neue Session. Fragen Sie erneut, während eine Übergabe wartet, erhalten Sie dieselbe Übergabe zurück, mit unverändertem Link, Grund und expiresAt.
  • Zweimal als erledigt markieren liefert dieselbe Antwort. Die Antwort ist 409 NO_HANDOFF, wenn keine Übergabe angefordert wurde, und 409 HANDOFF_EXPIRED, wenn sie vorher abgelaufen ist.
  • Solange eine Übergabe wartet, wird die Session nicht wegen Inaktivität geschlossen, auch wenn weder Ihr Skript noch die Person etwas tut. Das eigene timeoutSec der Session (aus der Erstellung), maxGb und Ihr Guthaben gelten weiterhin. Sobald die Übergabe erledigt oder abgelaufen ist, zählt das Inaktivitäts-Timeout ab diesem Moment neu.
  • Der Link ist ein Steuerungslink: Wer ihn hat, kann den Browser bis zum Ablauf steuern, angemeldet als derjenige, als der der Browser angemeldet ist. Senden Sie ihn nur an die Person, die handeln soll.
  • Ein handoff.requested-Webhook enthält dieselbe liveUrl, sodass ein Webhook-Handler den Link weitergeben kann (an einen Chat, eine E-Mail, ein Ticket), ohne dass Ihr Skript das übernehmen muss.

GET /api/v1/browsers/<id> zeigt die Übergabe. handoff ist null, bis Sie eine anfordern, und liveUrl ist null, solange state nicht waiting ist. Ist expiresAt ohne „I'm done“ verstrichen oder die Session vorher beendet worden, steht state auf timeout, und der Link funktioniert nicht mehr. Eine Session, die Sie selbst steuern, läuft weiter; ein Agent-Run endet (siehe unten).

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

Aus einem Skript

Ihr Skript bleibt während einer Übergabe verbunden. Warten Sie, bis die Person fertig ist, und machen Sie dann weiter:

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 fragt GET /api/v1/browsers/<id> alle 2 Sekunden ab, bis handoff.state nicht mehr waiting ist, und gibt diese Session-Ansicht zurück. Mit einem timeout (in Sekunden) hört es früher auf zu warten: Dann wird CloudTimeoutError ausgelöst, und die Übergabe bleibt offen. Um eine Übergabe von Ihrer Seite statt über den Button zu beenden, rufen Sie cloud.browsers.handoff_done(id) auf (Node: handoffDone(id)). Ohne SDK fragen Sie GET /api/v1/browsers/<id> alle paar Sekunden ab, bis handoff.state done (oder timeout) ist, oder warten auf den handoff.done-Webhook. Läuft eine Übergabe ab, wird kein Webhook gesendet; hören Sie deshalb spätestens bei expiresAt auf zu warten.

In Agent-Runs

Erstellen Sie den Run mit handoff: true. Wenn Jet anhält, weil ihm etwas fehlt, das es nicht hat (needs_input), oder weil es nicht weiterkommt (blocked), endet der Run nicht: Er pausiert als waiting_for_human, das handoff des Runs enthält die liveUrl, und ein handoff.requested-Webhook wird gesendet.

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}'
  • Wenn die Person „I'm done“ drückt, startet Jet erneut auf derselben Seite mit derselben Aufgabe und sieht die Seite so, wie sie sie verlassen hat (hat sie diesen Tab geschlossen, beginnt Jet wieder bei der url des Runs).
  • Ein Run kann bis zu dreimal übergeben werden. result.handoffs zählt die Übergaben, und die Schritte davor und danach stehen alle in result.steps.
  • handoffTimeoutSec (60 bis 3600, Standard 600) gibt an, wie lange jede Übergabe wartet. Wird niemand rechtzeitig fertig, endet der Run mit dem Status, bei dem Jet angehalten hat, also failed. Das eigene timeoutSec des Runs (Standard 900) läuft auch während einer Übergabe weiter: Erhöhen Sie es, wenn Sie handoffTimeoutSec erhöhen.
  • Verwenden Sie es mit einem profile und persist: true: Wo sich die Person anmeldet, wird gespeichert, und der nächste Run braucht sie nicht mehr.

Webhooks

Ein Webhook ist eine URL von Ihnen, an die wir einen signierten POST senden, wenn etwas passiert. Legen Sie ihn über die API, das SDK, die CLI oder die Dashboard-Einstellungen an:

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

Das secret steht nur in der Antwort beim Anlegen; damit prüfen Sie Signaturen. Verloren? Löschen Sie den Webhook und legen Sie einen neuen an.

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 ist null, bis etwas gesendet wurde. Sein status und der status eines Tests ist der HTTP-Status, mit dem Ihr Server geantwortet hat, oder null, wenn keine Antwort kam; ein fehlgeschlagener Test hat zusätzlich ein error mit dem Grund. Ein Test-Ping wird auch dann gesendet, wenn events den Eintrag ping nicht enthält.

Regeln

  • Höchstens 5 Webhooks pro Account; ein sechster ergibt 409 WEBHOOK_LIMIT. description umfasst bis zu 200 Zeichen in einer Zeile.
  • events legt fest, was gesendet wird (Tabelle unten). Lassen Sie es weg oder senden Sie eine leere Liste, um alles außer ping zu erhalten.
  • Die URL muss mit https:// beginnen, höchstens 2048 Zeichen lang sein, keinen Benutzernamen und kein Passwort enthalten und im öffentlichen Internet liegen. localhost, einteilige Namen (wie https://intranet) und IP-Adressen in privaten, Loopback-, Link-Local-, Carrier-Grade-NAT-, Multicast-, Dokumentations-, reservierten oder Cloud-Metadaten-Bereichen werden schon beim Anlegen des Webhooks abgelehnt, ebenso jede IPv6-Adresse, die eine IPv4-Adresse einbettet (::ffff:…). Bei jeder Zustellung wird der Hostname aufgelöst: Liegt eine seiner Adressen in diesen Bereichen, wird nichts gesendet, und der Versuch zählt als fehlgeschlagen.
  • Weiterleitungen werden nicht verfolgt, und jeder Versuch wartet höchstens 5 Sekunden auf eine Antwort. Antworten Sie schnell mit einem 2xx und erledigen Sie die Arbeit danach.

Events

typedataGesendet, wenn
session.started{ id, kind: "cdp" | "run", worker }Ein Browser wurde gestartet. kind ist "cdp" bei einer Session, die Sie selbst steuern, und "run" bei einem Agent-Run.
session.ended{ id, kind, reason, usage: { bytesUp, bytesDown, seconds }, costEur }Eine Session wurde beendet, mit Grund und Verbrauch. costEur ist eine einzelne Zahl: bei einem Run Browser und Agent zusammen. Eine Session im Zustand lost, die sich nie wieder meldet, sendet dieses Event, wenn sie endgültig beendet wird, mit dem Grund worker_silent, oder mit worker_restarted, sobald ihr Server nach einem Neustart wieder erreichbar ist.
run.finished{ id, status, result: { status, detail, url, title, output, outputError }, costEur }Ein Agent-Run ist beendet. status ist succeeded, failed oder cancelled; result ist der Hauptteil seines Ergebnisses oder null, wenn er keines hinterlassen hat; costEur ist { browser, agent, total }.
handoff.requested{ id, kind, reason, liveUrl, expiresAt }Ein Browser wurde an einen Menschen übergeben. Senden Sie liveUrl an die Person, die handeln soll.
handoff.done{ id, kind }Die Person hat „I'm done“ gedrückt, oder Sie haben die Übergabe als erledigt markiert (API oder Dashboard). Wird nicht gesendet, wenn eine Übergabe abläuft.
recording.ready{ id, bytes, durationSec }Eine Aufzeichnung steht zum Download bereit.
ping{}Wird vom Testaufruf gesendet, um Ihren Endpunkt zu prüfen.

id in data ist die ID der Session bzw. des Runs (beides ist dasselbe). Den vollständigen Zustand holen Sie mit GET /api/v1/runs/<id> oder GET /api/v1/browsers/<id>, wenn Sie mehr brauchen, als das Event enthält. Ein Run in der Warteschlange, der abgebrochen wird oder abläuft, bevor ein Server ihn übernimmt, sendet weder session.ended noch run.finished.

So sieht eine Zustellung aus

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

Wiederholungen

Eine Zustellung zählt, wenn Ihr Server mit einem 2xx antwortet. Alles andere (ein anderer Status, eine Weiterleitung, ein Timeout, eine abgelehnte Verbindung) wird erneut versucht. Insgesamt gibt es 6 Versuche: sofort, dann etwa 30 Sekunden, 2 Minuten, 10 Minuten, 1 Stunde und 6 Stunden nach dem Event. Nach dem sechsten wird die Zustellung als fehlgeschlagen markiert, und lastDelivery zeigt das an. Ein Test-Ping wird einmal gesendet und nie wiederholt.

  • Rechnen Sie mit Duplikaten. Eine Zustellung kann mehr als einmal ankommen, etwa wenn Ihre Antwort verloren ging. Clearcote-Webhook-Id (die id des Umschlags) ist bei jedem Versuch gleich: Überspringen Sie IDs, die Sie bereits verarbeitet haben.
  • Verlassen Sie sich nicht auf die Reihenfolge. Ein wiederholtes Event kann nach einem späteren ankommen. Verwenden Sie createdAt oder rufen Sie den aktuellen Zustand ab.

Signaturen prüfen

Jede Zustellung ist mit dem Secret Ihres Webhooks signiert:

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

Um eine Signatur zu prüfen, berechnen Sie denselben HMAC über den rohen Request-Body (die exakten Bytes, vor jedem JSON-Parsing), vergleichen ihn in konstanter Zeit mit v1 und lehnen ein t ab, das mehr als 5 Minuten von jetzt abweicht, damit eine alte Zustellung nicht erneut eingespielt werden kann. Das SDK erledigt all das mit einem Aufruf:

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) (auch aus clearcote importierbar) gibt das geparste Event zurück und löst ValueError aus, wenn der Header fehlt oder fehlerhaft ist, die Signatur nicht passt oder t außerhalb des Bereichs liegt. In Node macht verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) dasselbe, synchron, und wirft einen Error. raw_body kann Bytes oder ein String sein, der gesamte whsec_…-String ist der Schlüssel, und es genügt, wenn einer von mehreren v1-Werten passt. Auch ein fehlendes oder leeres Secret löst einen Fehler aus, sodass eine nicht gesetzte Umgebungsvariable nie eine Zustellung durchlässt. Übergeben Sie tolerance_sec=None (Node: null), um die Zeitprüfung zu überspringen, etwa beim erneuten Einspielen einer gespeicherten Zustellung.

In jeder Sprache

Kein SDK nötig: Es ist ein einfacher HMAC-SHA256 mit dem gesamten Secret-String (whsec_ eingeschlossen) als Schlüssel. In Python nur mit der Standardbibliothek:

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)

Und so prüfen Sie eine gespeicherte Zustellung von Hand:

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

Aktualisiert am 12. Okt. 2026 · SDK 0.70.5 · Browser r63

War diese Seite hilfreich?