Events

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:

{
  "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.

Hyperbrowser signs the raw JSON payload plus the X-Webhook-Timestamp header. See the overview 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.

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

You will receive a session.downloads.updated event each time the Downloads folder is updated in the browser session. Check out the Sessions Downloads 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.

{
  "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.

{
  "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.

{
  "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`).

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

Pair the session.closed event with the Sessions API 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.

{
  "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.

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

Event Filtering

From the dashboard you can choose exactly which events to deliver. Only the selected types will be enqueued.

Get Started

Browser Sessions

Session Configuration

Web API

Agents

HyperAgent Usage

Scraping

Webhooks

Integrations

Event Structure

Common fields

Session Events

`session.downloads.updated`

`session.tab.opened`

`session.captcha.detected`

`session.captcha.solved`

`session.closed`

`session.video_recording.completed`

`session.video_recording.failed`

Event Filtering

​Event Structure

​Common fields

​Session Events

​session.downloads.updated

​session.tab.opened

​session.captcha.detected

​session.captcha.solved

​session.closed

​session.video_recording.completed

​session.video_recording.failed

​Event Filtering

Event Structure

Common fields

Session Events

`session.downloads.updated`

`session.tab.opened`

`session.captcha.detected`

`session.captcha.solved`

`session.closed`

`session.video_recording.completed`

`session.video_recording.failed`

Event Filtering