Webhooks

Receive real-time notifications for task events.

Setup

1. Register webhook at https://cloud.browser-use.com/dashboard/webhooks
2. Verify signatures

Verification

Always verify webhook signatures.

1
import { verifyWebhookEventSignature, type WebhookAgentTaskStatusUpdatePayload } from "browser-use-sdk";
2
3
export async function POST(req: Request) {
4
    const signature = req.headers["x-browser-use-signature"] as string;
5
    const timestamp = req.headers["x-browser-use-timestamp"] as string;
6
7
    const event = await verifyWebhookEventSignature(
8
        {
9
            body,
10
            signature,
11
            timestamp,
12
        },
13
        {
14
            secret: SECRET_KEY,
15
        },
16
    );
17
18
    if (!event.ok) {
19
        return;
20
    }
21
22
    switch (event.event.type) {
23
        case "agent.task.status_update":
24
            break;
25
        case "test":
26
            break;
27
        default:
28
            break;
29
    }
30
}

Event Types and Payloads

All webhook events follow a consistent structure:

1
{
2
  "type": "event_type",
3
  "timestamp": "2024-01-01T00:00:00Z",
4
  "payload": {
5
    // Event-specific payload data
6
  }
7
}

agent.task.status_update

Sent when a task’s status changes. The payload contains:

• session_id (string): UUID of the session the task belongs to
• task_id (string): UUID of the task
• status (string): Current status of the task. Possible values:
  • "started": Task has started execution
  • "finished": Task completed successfully
  • "stopped": Task was stopped (manually or due to an error)
• metadata (object): Additional task metadata

Example payload:

1
{
2
  "type": "agent.task.status_update",
3
  "timestamp": "2024-01-01T12:00:00Z",
4
  "payload": {
5
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
6
    "task_id": "660e8400-e29b-41d4-a716-446655440000",
7
    "status": "finished",
8
    "metadata": {}
9
  }
10
}

test

Sent when testing a webhook configuration. The payload contains:

• test (string): Always "ok"

Example payload:

1
{
2
  "type": "test",
3
  "timestamp": "2024-01-01T12:00:00Z",
4
  "payload": {
5
    "test": "ok"
6
  }
7
}