Skip to main content
Webhooks reduces the need for polling. When you submit an inference request, include a webhook URL (and optionally webhook_intermediate_status: true). RunComfy will POST JSON updates to your endpoint until the run completes. The final success event includes the same outputs you would get from GET …/result. Base URL: https://api.runcomfy.net

​
Limitations

In production environments, especially for any network-dependent product, webhooks are never 100% guaranteed. Servers can restart, network routes can fail, and delivery can be delayed or dropped for many reasons. That’s why, even though webhooks reduce the need for polling, you should never rely on them alone. You should always pair webhooks with periodic polling to ensure results are received reliably in all production scenarios.

​
Enable Webhooks on Submit

POST /prod/v1/deployments/{deployment_id}/inference
Add two optional fields to the request body:
  • webhook is the HTTPS URL that will receive callbacks.
  • webhook_intermediate_status (default false) enables queue and in‑progress updates in addition to the final event. 
curl --request POST \
  --url https://api.runcomfy.net/prod/v1/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
  }'
The synchronous response is unchanged and still returns tracking URLs: 
{
  "request_id": "{request_id}",
  "status_url": "https://api.runcomfy.net/prod/v1/deployments/{deployment_id}/requests/{request_id}/status",
  "result_url": "https://api.runcomfy.net/prod/v1/deployments/{deployment_id}/requests/{request_id}/result",
  "cancel_url": "https://api.runcomfy.net/prod/v1/deployments/{deployment_id}/requests/{request_id}/cancel"
}

​
Webhook Events

We send HTTP POST requests with Content-Type: application/json. Payloads share a common shape and vary slightly by status.

​
In-Progress Update

{
  "request_id": "{request_id}",
  "deployment_id": "{deployment_id}",
  "status": "in_progress",
  "status_url": "https://api.runcomfy.net/prod/v1/deployments/dep_abc/requests/rq_123/status",
  "result_url": "https://api.runcomfy.net/prod/v1/deployments/dep_abc/requests/rq_123/result",
  "cancel_url": "https://api.runcomfy.net/prod/v1/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"
}
Statuses transition from in_progress to one of succeeded, failed, or cancelled. Determine completion from status.

​
Final Succeeded (includes outputs)

All results from the serverless API are automatically deleted after 7 days. If you need long-term or permanent storage, please save the results elsewhere. Everything generated is fully yours, we do not retain or serve your content publicly as a CDN. 
{
  "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"
}
The outputs schema matches the response from GET …/result.

​
Final 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"
}
The error object describes why the run failed (e.g., type, message). See Error Codes for common causes and fixes.

​
Delivery, Retries, and Idempotency

Acknowledge quickly by returning any 2xx within 10 seconds; perform heavy work asynchronously. If a delivery times out or returns a non‑2xx status, the system retries with exponential backoff for up to 24 hours. Deliveries can be duplicated or arrive out of order, so make handlers idempotent and deduplicate using request_id plus status (or your own event identifier).