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, 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)

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.

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

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

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

Deployment

API Reference

Pricing & Support

Webhooks

How to enable webhooks

Request example (with webhook)

Callback payloads

Example: in_queue

Example: in_progress

Example: succeeded

Example: failed

Delivery and retries

​How to enable webhooks

​Request example (with webhook)

​Callback payloads

​Example: in_queue

​Example: in_progress

​Example: succeeded

​Example: failed

​Delivery and retries

How to enable webhooks

Request example (with webhook)

Callback payloads

Example: in_queue

Example: in_progress

Example: succeeded

Example: failed

Delivery and retries