Batch Jobs & Webhooks

For processing many images at once and for reacting to events without polling, VIUCraft offers asynchronous batch jobs (with live SSE progress) and webhooks. Full request/response schemas for every endpoint below are in the OpenAPI spec and ready to try in the Postman collection.

Batch jobs

Submit a set of images + an operation pipeline, then track progress to completion. All paths are under your tenant host.

Create:

curl -X POST "https://<subdomain>.viucraft.com/api/v1/jobs" \
  -H "X-API-Key: vc_live_..." -H "Content-Type: application/json" \
  -d '{
    "image_ids": ["550e8400-...", "660e8400-..."],
    "operations": [ { "name": "resize", "params": { "width": 1200, "height": 630 } }, { "name": "sharpen" } ],
    "output_format": "webp"
  }'
# -> { "job_id": "job_...", "status": "queued", "task_count": 2 }

Track with SSE (don't poll). The stream emits progress events until the job finishes:

curl -N "https://<subdomain>.viucraft.com/api/v1/jobs/job_.../stream" \
  -H "X-API-Key: vc_live_..."
# event: progress
# data: {"completed": 1, "total": 2, "status": "processing"}
# event: complete
# data: {"status": "completed", "completed": 2, "total": 2}

The CLI wraps this as viucraft batch stream , and the SDK exposes it via client.batch.*.

Webhooks

Subscribe an HTTPS endpoint to events and VIUCraft will POST to it when they occur — no polling.

Create:

curl -X POST "https://<subdomain>.viucraft.com/api/webhooks" \
  -H "X-API-Key: vc_live_..." -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app.example.com/hooks/viucraft", "events": ["image.uploaded", "image.deleted", "batch.completed"] }'

Delivery payload (POSTed to your URL):

{
  "event": "image.deleted",
  "request_id": "req_...",
  "created_at": "2026-06-16T09:44:35+00:00",
  "data": { "image_id": "550e8400-...", "filename": "photo.png" }
}

Events include image lifecycle (image.uploaded, image.deleted) and batch completion (batch.completed). The exact event catalog and per-event data schemas are enumerated in the OpenAPI spec.

Verify and test:

1. Each delivery is signed; verify the signature header before trusting a payload (see the webhook reference in the spec).
2. Use POST /api/webhooks/{id}/test (or viucraft webhooks test ) to send yourself a sample event while building your handler.
3. Return a 2xx quickly; VIUCraft retries failed deliveries with backoff.