Skip to main content

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