For AI agents: a documentation index is available at /llms.txt
Skip to main content

Docker Webhooks

Configure the Docker image to call a URL when specific events occur, such as queuing, rejection, or errors. These webhook URLs are set as environment variables alongside the other Docker configuration options.

Prerequisites
  • A Browserless Enterprise license
  • Docker installed on your infrastructure
HTTP Method

All webhooks use the HTTP GET method with no request body. Browserless does not read the response. Respond quickly (HTTP 200/204) to close the connection.

Queuing​

QUEUE_ALERT_URL triggers a GET request to the specified URL when requests start queuing.

$ docker run -d \
  --restart always \
  --name browserless \
  -e "QUEUE_ALERT_URL=https://my.website.com/queued" \
  -p 3000:3000 \
  registry.browserless.io/browserless/browserless/enterprise:latest

Rejections​

REJECT_ALERT_URL triggers a GET request to the specified URL when requests are rejected.

$ docker run -d \
  --restart always \
  --name browserless \
  -e "REJECT_ALERT_URL=https://my.website.com/rejected" \
  -p 3000:3000 \
  registry.browserless.io/browserless/browserless/enterprise:latest

Timeouts​

TIMEOUT_ALERT_URL triggers a GET request to the specified URL when sessions time out.

$ docker run -d \
  --restart always \
  --name browserless \
  -e "TIMEOUT_ALERT_URL=https://my.website.com/time-out" \
  -p 3000:3000 \
  registry.browserless.io/browserless/browserless/enterprise:latest

Errors​

ERROR_ALERT_URL triggers a GET request to the specified URL when unhandled errors occur during request processing.

$ docker run -d \
  --restart always \
  --name browserless \
  -e "ERROR_ALERT_URL=https://my.website.com/error" \
  -p 3000:3000 \
  registry.browserless.io/browserless/browserless/enterprise:latest

When an error occurs, Browserless appends the error message as a query parameter:

GET https://my.website.com/error?error=Session%20timeout%20exceeded

No request body is sent. Parse the error query parameter to extract the message.

Health Failure​

FAILED_HEALTH_URL triggers a GET request to the specified URL when CPU and memory exceed 99%. Use this event to restart or replace the container.

$ docker run -d \
  --restart always \
  --name browserless \
  -e "FAILED_HEALTH_URL=https://my.website.com/failed-health" \
  -p 3000:3000 \
  registry.browserless.io/browserless/browserless/enterprise:latest

For webhooks for other events, contact us. You can also monitor container health programmatically using the /pressure utility endpoint.

FAQ & Troubleshooting​

How do I get an Enterprise license?

Contact sales@browserless.io or visit the pricing page for Enterprise plan details.

Can I run Browserless on my own infrastructure?

Yes. Enterprise customers can self-host using the Docker image. See Docker deployment for setup instructions.

Next steps​

Docker deployment

self-host Browserless with Docker

Launch parameters

configure your Enterprise deployment