Webhooks

Set up webhooks at cloud.browser-use.com/settings?tab=webhooks.

Events

Event	API	When
`agent.task.status_update`	V2	Task status changes (`started`, `finished`, `stopped`, or `failed`)
`session.status.update`	V3	Session status changes; inspect `payload.status`
`test`	Dashboard	Webhook test ping

Match the event type to the API version you use. For V4 run monitoring, see Observability and polling guidance.

Payload

A V2 task event includes task_id, session_id, status, and task metadata:

{
  "type": "agent.task.status_update",
  "timestamp": "2026-09-09T12:00:00Z",
  "payload": {
    "task_id": "task_abc123",
    "session_id": "session_xyz",
    "status": "finished",
    "metadata": {}
  }
}

A V3 event uses the session’s id as payload.session_id. output is included when available:

{
  "type": "session.status.update",
  "timestamp": "2026-09-09T12:00:00Z",
  "payload": {
    "session_id": "session_xyz",
    "status": "idle",
    "output": "The agent's result"
  }
}

Status-change events are not all completion events. Check the status before continuing your workflow.

Signature verification

Every webhook request includes two headers:

X-Browser-Use-Signature: lowercase hexadecimal HMAC-SHA256 signature.
X-Browser-Use-Timestamp: Unix timestamp in seconds when this delivery was sent.

The signed message is the UTF-8 encoding of {header_timestamp}.{canonical_payload}. The canonical payload is exactly Python’s json.dumps(payload, sort_keys=True, separators=(',', ':'), ensure_ascii=True), applied to the entire event, including its type, timestamp, and payload. This is not a signature over the raw HTTP body. The sender serializes the HTTP body separately. Non-ASCII characters are escaped in the signed representation: for example, München becomes M\u00fcnchen.

JavaScript JSON.stringify, even after sorting an object’s keys, does not implement this format. Unicode escaping, integer-like object keys, and number formatting can differ from Python. Do not use a generic JavaScript JSON canonicalizer or raw-body HMAC verifier for this contract. The Python verifier below matches the current sender; other implementations must match its serialization exactly and preserve number representations when parsing.

Save this as webhook_verify.py:

import hashlib
import hmac
import json
import re
import time


def verify_webhook(body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    if not isinstance(timestamp, str) or not re.fullmatch(r"[0-9]{1,12}", timestamp):
        return False
    if abs(time.time() - int(timestamp)) > 300:
        return False
    if not isinstance(signature, str) or not re.fullmatch(r"[0-9a-f]{64}", signature):
        return False

    try:
        payload = json.loads(body)
        if not isinstance(payload, dict):
            return False
        canonical = json.dumps(
            payload, sort_keys=True, separators=(",", ":"),
            ensure_ascii=True, allow_nan=False,
        )
    except (ValueError, TypeError, UnicodeError):
        return False

    message = f"{timestamp}.{canonical}".encode("utf-8")
    expected = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

The five-minute timestamp window limits replay, but does not make delivery unique. Make your business action idempotent so a duplicate callback cannot process the same result twice. Keep your server clock synchronized.

Example: FastAPI webhook handler

Install fastapi and uvicorn, put this app.py beside webhook_verify.py, set WEBHOOK_SECRET to the signing secret from your webhook settings, and run uvicorn app:app --port 3000.

import json
import os

from fastapi import FastAPI, HTTPException, Request
from webhook_verify import verify_webhook

app = FastAPI()
WEBHOOK_SECRET = os.environ["WEBHOOK_SECRET"]


@app.post("/webhook")
async def handle_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-browser-use-signature", "")
    timestamp = request.headers.get("x-browser-use-timestamp", "")

    if not verify_webhook(body, signature, timestamp, WEBHOOK_SECRET):
        raise HTTPException(status_code=401, detail="Invalid webhook signature or timestamp")

    event = json.loads(body)
    if event.get("type") in {"agent.task.status_update", "session.status.update"}:
        data = event["payload"]
        # Persist or enqueue the verified event for your application to process.
        # Deduplicate before applying business side effects.
        print(f"Session {data['session_id']} is now {data['status']}")

    return {"status": "ok"}

Return promptly after durably accepting the event. The sender has a 10-second request timeout and retries temporary failures, so slow processing can cause duplicate deliveries. HTTP 400, 401, 403, 404, and 410 are not retried.

For local development, expose your local server with a tool such as ngrok: ngrok http 3000. Set the resulting /webhook URL in the dashboard and use its test action before starting tasks.

Get Started

Pillars

More

Events

Payload

Signature verification

Example: FastAPI webhook handler

​Events

​Payload

​Signature verification

​Example: FastAPI webhook handler

Events

Payload

Signature verification

Example: FastAPI webhook handler