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

# Webhooks

Webhooks let RunComfy **push request updates to your server** instead of requiring polling.

When enabled on a request:

* RunComfy sends `POST` callbacks with status/progress updates
* you can react immediately (store results, update UI, trigger downstream jobs)
* you can reduce or eliminate polling load

***

## How to enable webhooks

When you submit an inference request, pass webhook options as **query parameters**:

* `webhook`: your HTTPS endpoint that will receive callbacks (**URL-encoded**)
* `webhook_intermediate_status`: set to `true` to receive intermediate updates (in queue / in progress)

```text theme={null}
POST /prod/v2/deployments/{deployment_id}/inference?webhook={url_encoded_webhook}&webhook_intermediate_status=true
```

> Note: Because the webhook URL is part of the query string, it must be URL-encoded.
> Example: `https://example.com/api/runcomfy/webhook` → `https%3A%2F%2Fexample.com%2Fapi%2Fruncomfy%2Fwebhook`

### Request example (with webhook)

The request body must conform to the deployment’s input schema shown on the deployment details page under the **API** tab.

```bash theme={null}
curl --request POST \
  --url 'https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/inference?webhook=https%3A%2F%2Fexample.com%2Fapi%2Fruncomfy%2Fwebhook&webhook_intermediate_status=true' \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "prompt": "Make the scene feel warmer and more cinematic. Add a subtle orange glow.",
    "ctrl_img_1": "https://playgrounds-storage-public.runcomfy.net/tools/7063/media-files/usecase1-1-input.webp",
    "width": 1024,
    "height": 1024,
    "guidance_scale": 4,
    "sample_steps": 25,
    "network_multiplier": 1.0,
    "neg": "",
    "seed": 42,
    "sampler": "flowmatch",
    "num_frames": 1,
    "fps": 1
  }'
```

***

## Callback payloads

Callbacks are delivered as JSON. Payload shape depends on the current state of the request.

Common fields you’ll see:

* `request_id`
* `deployment_id`
* `status` and/or `outcome`
* `created_at` / `finished_at`
* `output` (on success) — matches the output schema you get from **[GET …/result](/serverless-lora/async-queue-endpoints#retrieve-request-results)**

### Example: in\_queue

```json theme={null}
{
  "request_id": "{request_id}",
  "status_url": "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/status",
  "result_url": "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/result",
  "cancel_url": "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/cancel"
}
```

### Example: in\_progress

```json theme={null}
{
  "request_id": "{request_id}",
  "deployment_id": "{deployment_id}",
  "status": "in_progress",
  "status_url": "https://api.runcomfy.net/prod/v2/deployments/dep_abc/requests/rq_123/status",
  "result_url": "https://api.runcomfy.net/prod/v2/deployments/dep_abc/requests/rq_123/result",
  "cancel_url": "https://api.runcomfy.net/prod/v2/deployments/dep_abc/requests/rq_123/cancel",
  "instance_id": "{instance_id}",
  "created_at": "2025-11-18T10:00:00Z",
  "started_at": "2025-11-18T10:01:00Z"
}
```

### Example: succeeded

```json theme={null}
{
  "request_id": "{request_id}",
  "deployment_id": "{deployment_id}",
  "status": "succeeded",
  "output": {
    "images": [
      "https://example.com/output-1.png",
      "https://example.com/output-2.png"
    ]
  },
  "instance_id": "{instance_id}",
  "created_at": "2025-11-18T10:00:00Z",
  "started_at": "2025-11-18T10:01:12Z",
  "finished_at": "2025-11-18T10:08:30Z"
}
```

### Example: failed

```json theme={null}
{
  "request_id": "{request_id}",
  "deployment_id": "{deployment_id}",
  "status": "failed",
  "error": {
    "error": "ExampleErrorType",
    "details": "This is an example error message explaining the failure.",
    "debugInfo": "Example debug information or stack trace here.",
    "errorCode": 12345
  },
  "instance_id": "{instance_id}",
  "created_at": "2025-11-18T10:00:00Z",
  "started_at": "2025-11-18T10:01:12Z",
  "finished_at": "2025-11-18T10:08:30Z"
}
```

***

## Delivery and retries

* Your webhook endpoint should respond with **2xx** quickly.
* Non-2xx responses may trigger retries.
* Keep your handler idempotent (you may receive the same event more than once).

If a request fails and you need troubleshooting guidance, see **[Error Codes](/serverless-lora/error-codes)**.