Integration patterns

Lifecycle

submit job → queued → running → succeeded | failed | canceled
                                  └→ signed webhook

The input and output are runtime-defined JSON. The queue, idempotency, retries, provenance, cancellation and webhooks are generic.

Safe submission

import httpx

response = httpx.post(
    f"{NESTOR}/v1/endpoints/{endpoint_id}/jobs",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": application_request_id,
    },
    json={
        "input": runtime_input,
        "metadata": {"application_request_id": application_request_id},
        "webhook_url": "https://example.com/hooks/nestor",
    },
    timeout=30,
)
response.raise_for_status()
job_id = response.json()["id"]

Retry a failed client request with the same idempotency key. Nestor returns the original job rather than executing it twice. Metadata is echoed on reads and webhooks.

Runtime input

For generic_http, input is forwarded as the configured JSON HTTP request:

{"input":{"messages":[{"role":"user","content":"Hello"}],"max_tokens":64}}

For comfyui, submit API-format workflow JSON:

{"input":{"workflow":{"3":{"class_type":"KSampler","inputs":{}}}}}

ComfyUI workflow validation, deterministic negative-seed resolution, input-image staging and artifact discovery are driver behavior. They do not apply to other runtimes.

Webhook verification

Verify the signature over the raw request body:

import hashlib
import hmac

message = f"{webhook_id}.{timestamp}.".encode() + raw_body
expected = "v1=" + hmac.new(
    webhook_secret.encode(), message, hashlib.sha256
).hexdigest()
if not hmac.compare_digest(expected, signature):
    raise Unauthorized()

Delivery is at least once. Deduplicate using Nestor-Webhook-Id, respond with 2xx quickly, and process asynchronously. A job remains queryable if webhook delivery is exhausted.

Provenance and rollouts

Every completed job records its immutable deployment_id and resolved image_digest. During drain-and-roll, jobs already running finish on the old revision; new work moves to the new revision as slots become ready.

Pin production images by digest. Check deployment convergence before declaring a release complete.

Failure handling

Runtime drivers map protocol errors into generic job errors. Infrastructure loss may retry under the existing lease policy. Invalid runtime input and runtime application failures should be corrected rather than blindly resubmitted.

Use job.attempt, job.error, the deployment revision and image digest when investigating.

Artifacts

Artifact-producing drivers return metadata and presigned object-storage URLs. Artifact bytes do not transit the control plane. URLs expire; copy durable outputs to customer-controlled storage.