> ## Documentation Index
> Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Complete catalog of Hyperbrowser webhook payloads

This page documents each event, how to trigger it, and the payload shape you should expect at your listener.

## Event Structure

All webhooks follow the same envelope:

```json theme={null}
{
  "type": "session.downloads.updated",
  "data": {
    "sessionId": "sess_123",
    "path": "sandstorm.mp3",
    "updatedAt": 1730935567123
  },
  "timestamp": 1730935567345,
  "eventId": "6fdb752a-d7e0-4fd7-97fd-1d8bf2e9c71e"
}
```

### Common fields

| Field | Type | Description |
| - | - | - |
| `type` | string | Event type identifier (see sections below). |
| `data` | object | Event-specific payload, documented per event. |
| `timestamp` | number | Unix timestamp in milliseconds when the event was generated. |
| `eventId` | string | UUID for deduplication. Store processed IDs to ensure idempotency. |

> [!TIP]
>
> Hyperbrowser signs the raw JSON payload plus the `X-Webhook-Timestamp` header. See the [overview](https://hyperbrowser.ai/docs/webhooks/overview.md) for signature validation details.

## Session Events

Events in this category are emitted by browser sessions launched through the Sessions API. Webhook enabling or disabling in the dashboard will only apply to new sessions created after the change.

### `session.downloads.updated`

Sent each time the Downloads folder is updated in a session where `saveDownloads` was enabled.

* **Triggered by:** Downloads folder is updated in the browser session.
* **Prerequisites:** `saveDownloads: true` during session creation.

| Data field | Type | Description |
| - | - | - |
| `sessionId` | string | ID of the session that generated the download. |
| `path` | string | Relative path to the updated entity in the Downloads folder. |
| `updatedAt` | number | Unix timestamp (ms) when the Downloads folder was updated. |

```json theme={null}
{
  "type": "session.downloads.updated",
  "data": {
    "sessionId": "sess_9w41qdy8",
    "path": "new-folder",
    "updatedAt": 1731532800451
  },
  "timestamp": 1731532800475,
  "eventId": "e6d33510-6c92-4b8a-9515-86f0c817c52c"
}
```

> [!NOTE]
>
> You will receive a `session.downloads.updated` event each time the Downloads folder is updated in the browser session. Check out the [Sessions Downloads](https://hyperbrowser.ai/docs/sessions/downloads.md) docs for more information on how to retrieve the downloads folder.

### `session.tab.opened`

Sent whenever a new browser tab is opened during a session.

* **Triggered by:** A new page target is created (tab or popup).
* **Prerequisites:** None.

| Data field | Type | Description |
| - | - | - |
| `sessionId` | string | Session ID. |
| `targetId` | string \| null | Target ID for the new tab. |
| `pageUrl` | string \| null | Page URL when the tab opened. |

```json theme={null}
{
  "type": "session.tab.opened",
  "data": {
    "sessionId": "sess_9w41qdy8",
    "targetId": "target-1",
    "pageUrl": "https://example.com"
  },
  "timestamp": 1731532850012,
  "eventId": "f5221cdd-4bd6-4b30-8a0c-6b9e12e27d8b"
}
```

### `session.captcha.detected`

Sent when a captcha is detected during a session.

* **Triggered by:** Captcha detection in the browser (recaptcha/turnstile, etc.).
* **Prerequisites:** Captcha solving enabled for the session (e.g. `solveCaptchas: true`).

| Data field | Type | Description |
| - | - | - |
| `sessionId` | string | Session ID. |
| `targetId` | string \| null | Target/frame identifier if available. |
| `pageUrl` | string \| null | Page URL where the captcha was detected. |
| `captcha` | string | Captcha type (for example `recaptcha`). |
| `status` | string | Status string (typically `detected`). |
| `error` | string | Error message if detection failed. |

```json theme={null}
{
  "type": "session.captcha.detected",
  "data": {
    "sessionId": "sess_9w41qdy8",
    "targetId": "target-1",
    "pageUrl": "https://example.com",
    "captcha": "recaptcha",
    "status": "detected"
  },
  "timestamp": 1731532900123,
  "eventId": "1e7b5b4f-8c6c-4a0e-82e9-7cf1ef2f6d10"
}
```

### `session.captcha.solved`

Sent when a captcha is solved during a session.

* **Triggered by:** Captcha solving completing successfully.
* **Prerequisites:** Captcha solving enabled for the session (e.g. `solveCaptchas: true`).

| Data field | Type | Description |
| - | - | - |
| `sessionId` | string | Session ID. |
| `targetId` | string \| null | Target/frame identifier if available. |
| `pageUrl` | string \| null | Page URL where the captcha was solved. |
| `captcha` | string | Captcha type (for example `recaptcha`). |
| `status` | string | Status string (typically `solved`). |
| `error` | string | Error message if solving failed. |

```json theme={null}
{
  "type": "session.captcha.solved",
  "data": {
    "sessionId": "sess_9w41qdy8",
    "targetId": "target-1",
    "pageUrl": "https://example.com",
    "captcha": "recaptcha",
    "status": "solved"
  },
  "timestamp": 1731532920456,
  "eventId": "a7b1b9b0-28a2-4f5f-9e18-2d5a7edb6f8a"
}
```

### `session.closed`

Sent whenever a session closes.

* **Triggered by:** Session lifecycle ending.

| Data field | Type | Description |
| - | - | - |
| `sessionId` | string | Session ID. |
| `status` | string | Final state (one of `active`, `closed`, `error`). |

```json theme={null}
{
  "type": "session.closed",
  "data": {
    "sessionId": "sess_9w41qdy8",
    "status": "closed"
  },
  "timestamp": 1731532950123,
  "eventId": "0b0e2505-9d47-41be-8e98-6a5ab5a8c88d"
}
```

> [!TIP]
>
> Pair the `session.closed` event with the [Sessions API](https://hyperbrowser.ai/docs/sessions/lifecycle.md#getting-session-details) to pull final details of the session as soon as it stops.

### `session.video_recording.completed`

Sent when a session's video recording has been successfully finalized and is ready for playback or download.

* **Triggered by:** Video recording finalization completing successfully.
* **Prerequisites:** Video recording enabled for the session.

| Data field | Type | Description |
| - | - | - |
| `sessionId` | string | ID of the session whose recording completed. |

```json theme={null}
{
  "type": "session.video_recording.completed",
  "data": {
    "sessionId": "sess_9w41qdy8"
  },
  "timestamp": 1731533000123,
  "eventId": "c3a1b2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}
```

### `session.video_recording.failed`

Sent when a session's video recording failed to finalize.

* **Triggered by:** Video recording finalization encountering an error.
* **Prerequisites:** Video recording enabled for the session.

| Data field | Type | Description |
| - | - | - |
| `sessionId` | string | ID of the session whose recording failed. |

```json theme={null}
{
  "type": "session.video_recording.failed",
  "data": {
    "sessionId": "sess_9w41qdy8"
  },
  "timestamp": 1731533050456,
  "eventId": "d4b2c3e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
}
```

## Event Filtering

From the [dashboard](https://app.hyperbrowser.ai/settings?tab=webhooks) you can choose exactly which events to deliver. Only the selected types will be enqueued.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.