Polling & webhooks

There are two ways to learn when a task finishes: poll the task endpoint, or have ZekronAI call your server with a webhook.

Polling

Retrieve the task on an interval until status is succeeded or failed. We recommend polling every 1–2 seconds for image and tool tasks, and every 3–5 seconds for video.

javascript

async function waitForTask(id, key) {
  while (true) {
    const res = await fetch("https://api.zekron.tech/api/v1/task/" + id, {
      headers: { Authorization: "Bearer " + key },
    })
    const task = await res.json()
    if (task.status === "succeeded") return task.output
    if (task.status === "failed") throw new Error(task.error.message)
    await new Promise((r) => setTimeout(r, 2000))
  }
}

Webhooks

Pass a webhook_url when creating a task and ZekronAI will send a POST request to it once the task reaches a terminal state. This avoids polling entirely.

json

POST https://your-app.com/zekron/webhook

{
  "event": "task.succeeded",
  "task": {
    "id": "zk_task_8f3a2b1c9d",
    "status": "succeeded",
    "output": { "images": ["https://cdn.zekron.tech/out/8f3a2b1c9d.png"] }
  }
}

Verifying webhooks

Each webhook includes an X-Zekron-Signature header — an HMAC SHA-256 of the raw request body using your webhook signing secret. Recompute it and compare to confirm the request genuinely came from ZekronAI.

Output URLs are time-limited. Download and store any assets you need to keep; do not hotlink to the ZekronAI CDN long-term.