Skip to main content
Set up webhooks at cloud.browser-use.com/settings?tab=webhooks.

​
Events

EventWhen
agent.task.status_updateTask status changes (started, finished, or stopped)
testWebhook test ping

​
Payload

{
  "type": "agent.task.status_update",
  "timestamp": "2025-01-15T10:30:00Z",
  "payload": {
    "task_id": "task_abc123",
    "session_id": "session_xyz",
    "status": "finished",
    "metadata": {}
  }
}

​
Signature verification

Every webhook request includes two headers:
  • X-Browser-Use-Signature — HMAC-SHA256 signature of the payload
  • X-Browser-Use-Timestamp — Unix timestamp (seconds) when the request was sent
The signature is computed over {timestamp}.{body}, where body is the JSON-serialized payload with keys sorted alphabetically and no extra whitespace. Verify it to ensure the request is authentic and to prevent replay attacks. 
import hashlib
import hmac
import json
import time

def verify_webhook(body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    # Reject requests older than 5 minutes
    if abs(time.time() - int(timestamp)) > 300:
        return False
    payload = json.loads(body)
    message = f"{timestamp}.{json.dumps(payload, separators=(',', ':'), sort_keys=True)}"
    expected = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)