Webhooks
When one of your batches ends, Zabio can send a signed POST to addresses you choose, so you do not have to poll GET /v1/batches/{id}. The request follows the Standard Webhooks specification, so any of its libraries verifies it, and the code below does the same in a few lines.
Events
Section titled “Events”| Event | Sent when the batch |
|---|---|
batch.completed |
finished: every line has a result or an error |
batch.failed |
failed before it ran (a bad file, too little credit), or could not be finished because of an error on Zabio’s side |
batch.expired |
reached its 24-hour window with lines still open |
batch.cancelled |
was cancelled, by you or by Zabio after an error on its side, and the work in flight has ended |
Each event is sent once per endpoint. An endpoint receives every event type; read type to choose what to do.
Add an endpoint
Section titled “Add an endpoint”In the web app, open Settings, then Webhooks, and choose Add endpoint. Owners and admins can add, rotate and remove endpoints; members do not see the section. The address must be public https, without a user name or password in it, at most 2,048 characters. An organization has at most 10 endpoints.
When you add the endpoint, Zabio shows its signing secret once, a value that starts with whsec_. Copy it into your application’s secret store: it cannot be shown again. If it is lost, rotate it.
The request
Section titled “The request”POST /your/path HTTP/1.1Content-Type: application/jsonUser-Agent: Zabio-Webhooks/1.0webhook-id: evt_019a6d1c7e2b7f3c8a9d0e1f2a3b4c5dwebhook-timestamp: 1762646400webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4={ "id": "evt_019a6d1c7e2b7f3c8a9d0e1f2a3b4c5d", "type": "batch.completed", "timestamp": "2026-11-09T00:00:00.123456Z", "data": { "id": "batch_019a6c0b5d4e7a1b9c8d7e6f5a4b3c2d", "object": "batch", "endpoint": "/v1/chat/completions", "status": "completed", "request_counts": { "total": 1000, "completed": 998, "failed": 2 }, "output_file_id": "file_019a6d1c7a0b7c2d8e9f0a1b2c3d4e5f", "error_file_id": "file_019a6d1c7a1c7d3e8f9a0b1c2d3e4f5a", "created_at": 1762560000, "ended_at": 1762646400, "links": { "batch": "https://api.zabio.ai/v1/batches/batch_019a6c0b5d4e7a1b9c8d7e6f5a4b3c2d", "output": "https://api.zabio.ai/v1/files/file_019a6d1c7a0b7c2d8e9f0a1b2c3d4e5f/content", "errors": "https://api.zabio.ai/v1/files/file_019a6d1c7a1c7d3e8f9a0b1c2d3e4f5a/content" } }}The body never carries a prompt or an answer: the batch’s id, status, counts and links only. The links need your API key, like any other call; output_file_id, error_file_id and their links are null when the batch has no such file. created_at and ended_at are Unix seconds; timestamp is when the event happened.
webhook-idis the event’s id. It is the same on every retry, so use it to ignore a delivery you already handled.webhook-timestampis when this attempt was sent, in Unix seconds. Each retry has a new one.webhook-signatureisv1,and the base64 HMAC-SHA256, keyed with your secret, ofwebhook-id, a full stop,webhook-timestamp, a full stop and the raw body. During a rotation there are two signatures, separated by a space.
Verify the signature
Section titled “Verify the signature”Check the signature over the raw body, as received, before you parse it, and refuse a timestamp more than five minutes from your clock. The key is the base64 text after whsec_, decoded.
Python
import base64, hashlib, hmac, time
def verify(secret: str, headers: dict, body: bytes, tolerance: int = 300) -> bool: msg_id = headers["webhook-id"] timestamp = headers["webhook-timestamp"] if abs(time.time() - int(timestamp)) > tolerance: return False key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{msg_id}.{timestamp}.".encode() + body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() for signature in headers["webhook-signature"].split(" "): version, _, value = signature.partition(",") if version == "v1" and hmac.compare_digest(value, expected): return True return FalseNode.js
import crypto from "node:crypto";
export function verify(secret, headers, rawBody, toleranceSeconds = 300) { const id = headers["webhook-id"]; const timestamp = headers["webhook-timestamp"]; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false; const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.`).update(rawBody).digest(); return headers["webhook-signature"].split(" ").some((signature) => { const [version, value] = signature.split(","); if (version !== "v1" || !value) return false; const got = Buffer.from(value, "base64"); return got.length === expected.length && crypto.timingSafeEqual(got, expected); });}To check your code: with the secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw, the id msg_p5jXN8AQM9LWM0D4loKWxJek, the timestamp 1614265330 and the body {"test": 2432232314}, the signature is v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= (the Standard Webhooks reference test).
Answer and retries
Section titled “Answer and retries”Answer with any 2xx status within 15 seconds; the body of your answer is ignored. Do the work after you answer, or queue it, so a slow job does not count as a failure. Anything else is a failed attempt: another status, a timeout, a connection or TLS error, and a redirect, which is not followed.
A failed delivery is tried again after about 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 14 hours (each wait varies by up to a tenth): 8 attempts over about 31 and a half hours, then it is marked failed. The batch itself never waits for a webhook. Deliveries are sent as soon as the batch ends; they can arrive out of order, and in rare cases the same event can arrive twice, which webhook-id lets you detect.
Zabio sends only to public addresses: an address whose name resolves to a private or internal network is refused at each attempt and counts as failed.
Rotate the secret
Section titled “Rotate the secret”Rotate secret creates a new secret and shows it once. For the next 24 hours each event is signed with both secrets, two signatures in webhook-signature, so you can deploy the new one without missing a delivery; after that only the new secret signs. Rotating again within the 24 hours drops the oldest.
See the deliveries
Section titled “See the deliveries”Deliveries under each endpoint lists its newest 50 deliveries: the event, the batch, the status (delivered, retrying with the time of the next try, failed or cancelled), the attempts and the last answer, a status code or the kind of error (timeout, dns, tls, connection, non_public_address). Removing an endpoint cancels the retries waiting for it.
What is kept, and for how long
Section titled “What is kept, and for how long”The signing secret is stored encrypted with your organization’s key and is never shown after the add or the rotation. Each event, its deliveries and their attempts are kept 30 days. Zabio never keeps the body of your answer, and never writes the secret or the path and query of your address to its logs.