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