Use this reference to implement a webhook endpoint for a serverless agent pool. The endpoint receives a request from Scalr, asks your container platform to start an agent for the requested task, and responds once the launch request is accepted.

For a complete AWS example, follow Serverless Agent Pool on AWS Fargate.

Request body

When a run reaches a stage that needs an agent, Scalr sends an HTTP POST request to the pool's webhook URL with this JSON body:

{
  "task_id": "{agent_task_id}",
  "action": "{action}",
  "run_id": "{run_id}",
  "workspace_id": "{workspace_id}",
  "environment_id": "{environment_id}",
  "created_at": "{created_at}"
}

Field	Description
`task_id`	ID of the agent task assigned to the container.
`action`	Task type, such as `plan`, `apply`, `policy.check`, or `checkov`.
`run_id`	ID of the run that the agent task belongs to.
`workspace_id`	ID of the workspace.
`environment_id`	ID of the environment.
`created_at`	Task creation time, such as `2026-11-02T10:15:00+0000`.

Headers

Header	Value
`Content-Type`	`application/json`
`Idempotency-Key`	The agent task ID. The value stays the same across delivery retries.
Custom headers	Values configured on the agent pool, such as an endpoint's `x-api-key`.

Response and retries

The webhook handler must request an agent container launch from the container platform. Once the platform accepts the launch request, the handler must return an HTTP 2xx response to Scalr without waiting for the agent to connect or complete its task. If the launch request fails, the handler must return a non-2xx response.

Behavior	Contract
Connection timeout	3 seconds.
Response timeout	15 seconds.
Successful delivery	Any HTTP `2xx` status. No specific response body is required.
Failed delivery	A non-`2xx` status, timeout, or connection failure. Scalr retries, up to 3 attempts in total.
Retry delay	2 seconds before the second attempt, then 4 seconds before the third.

Scalr stops retrying if the agent task is no longer pending, for example because it was acquired or the run was canceled. Your endpoint can therefore receive fewer than 3 attempts.

A 2xx response stops webhook retries, even if the container later fails to start.

A request can be delivered more than once, including when Scalr times out after your endpoint has already started a container. Use Idempotency-Key to recognize retries and avoid launching another container for a request already accepted. If your container platform supports idempotent launches, pass a stable token derived from this header.

Endpoint reachability

The webhook endpoint must be publicly reachable. Agent containers can run in a private network with the required outbound access.

Endpoint access controls

Under Headers on the agent pool, add the header names and credential values your endpoint requires. Scalr sends those header values with each request. A configured header is a static value, not a signature calculated from the request body.

Use separate credentials for the endpoint and the agent. The agent pool token belongs in the container's SCALR_AGENT_TOKEN environment variable. It authenticates the agent to Scalr and is not a webhook credential.

Agent container settings

Use the scalr/agent image, or a custom agent image with the tools your runs need.

Environment variable	Value	Purpose
`SCALR_AGENT_TOKEN`	The agent pool token, injected from a secret store	Connects the agent to its pool.
`SCALR_AGENT_SINGLE`	`true`	Runs one agent task, then exits.
`SCALR_AGENT_DRIVER`	`local`	Optional override of automatic driver selection. Executes the task inside the agent container.
`SCALR_URL`	Your Scalr account URL	Sets the Scalr API endpoint. Optional.
`SCALR_AGENT_LOG_FORMAT`	`json`	Enables structured logs for troubleshooting. Optional.

On Fargate, the agent selects local automatically. On other Linux container platforms, it also selects local when neither a Docker connection nor Kubernetes access is configured. If your platform provides either connection, set SCALR_AGENT_DRIVER=local to keep task execution inside the agent container.

Configure the container platform to launch a standalone task or job. A service that maintains a desired number of containers can restart an agent after it exits.