RunComfy API Docs

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, you can pass webhook options as query parameters (recommended):

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

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

Recommended request example (query parameters)

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 '{
    "overrides": { }
  }'

Legacy request example (request body)

The following body-based fields are still supported, but they are considered legacy and are not the primary recommended approach:

webhook
webhook_intermediate_status

curl --request POST \
  --url https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/inference \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "overrides": { },
    "webhook": "https://example.com/api/runcomfy/webhook",
    "webhook_intermediate_status": true
  }'

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

Example: in_queue

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

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

{
  "request_id": "{request_id}",
  "deployment_id": "{deployment_id}",
  "status": "succeeded",
  "outputs": {
    "136": {
      "images": [
        {
          "url": "https://example.com/ComfyUI_00001_.png",
          "filename": "ComfyUI_00001_.png",
          "subfolder": "",
          "type": "output"
        }
      ]
    }
  },
  "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

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

Getting Started

Workflows

Deployment

API Reference

Pricing & Support

Webhooks

How to enable webhooks

Recommended request example (query parameters)

Legacy request example (request body)

Callback payloads

Example: in_queue

Example: in_progress

Example: succeeded

Example: failed

Delivery and retries

​How to enable webhooks

​Recommended request example (query parameters)

​Legacy request example (request body)

​Callback payloads

​Example: in_queue

​Example: in_progress

​Example: succeeded

​Example: failed

​Delivery and retries

How to enable webhooks

Recommended request example (query parameters)

Legacy request example (request body)

Callback payloads

Example: in_queue

Example: in_progress

Example: succeeded

Example: failed

Delivery and retries