Webhooks
Cuando termina uno de tus lotes, Zabio puede enviar un POST firmado a las direcciones que elijas, así no tienes que consultar GET /v1/batches/{id}. La petición sigue la especificación Standard Webhooks, de modo que cualquiera de sus bibliotecas la verifica, y el código de abajo hace lo mismo en pocas líneas.
Eventos
Section titled “Eventos”| Evento | Se envía cuando el lote |
|---|---|
batch.completed |
terminó: cada línea tiene un resultado o un error |
batch.failed |
falló antes de ejecutarse (un archivo con errores, crédito insuficiente), o no pudo terminarse por un error por parte de Zabio |
batch.expired |
llegó al final de su ventana de 24 horas con líneas abiertas |
batch.cancelled |
se canceló, por ti o por Zabio tras un error por su parte, y terminó el trabajo en curso |
Cada evento se envía una vez a cada endpoint. Un endpoint recibe todos los tipos de evento; lee type para decidir qué hacer.
Añadir un endpoint
Section titled “Añadir un endpoint”En la aplicación web, abre Ajustes, luego Webhooks, y elige Añadir endpoint. Los propietarios y administradores pueden añadir, rotar y quitar endpoints; los miembros no ven la sección. La dirección debe ser https pública, sin usuario ni contraseña, de 2.048 caracteres como máximo. Una organización tiene como máximo 10 endpoints.
Al añadir el endpoint, Zabio muestra su secreto de firma una sola vez, un valor que empieza por whsec_. Cópialo en el almacén de secretos de tu aplicación: no se puede volver a mostrar. Si lo pierdes, rótalo.
La petición
Section titled “La petición”POST /tu/ruta 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" } }}El cuerpo nunca lleva un prompt ni una respuesta: solo el id del lote, su estado, los recuentos y los enlaces. Los enlaces necesitan tu API key, como cualquier otra llamada; output_file_id, error_file_id y sus enlaces son null cuando el lote no tiene ese archivo. created_at y ended_at son segundos Unix; timestamp es cuándo ocurrió el evento.
webhook-ides el id del evento. Es el mismo en cada reintento, así que úsalo para ignorar una entrega que ya procesaste.webhook-timestampes cuándo se envió este intento, en segundos Unix. Cada reintento tiene uno nuevo.webhook-signatureesv1,y el HMAC-SHA256 en base64, con tu secreto como key, dewebhook-id, un punto,webhook-timestamp, un punto y el cuerpo tal cual. Durante una rotación hay dos firmas separadas por un espacio.
Verificar la firma
Section titled “Verificar la firma”Comprueba la firma sobre el cuerpo sin procesar, tal como llega, antes de interpretarlo, y rechaza una marca de tiempo a más de cinco minutos de tu reloj. La key es el texto base64 que sigue a whsec_, decodificado.
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); });}Para probar tu código: con el secreto whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw, el id msg_p5jXN8AQM9LWM0D4loKWxJek, la marca de tiempo 1614265330 y el cuerpo {"test": 2432232314}, la firma es v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= (la prueba de referencia de Standard Webhooks).
Respuesta y reintentos
Section titled “Respuesta y reintentos”Responde con cualquier estado 2xx en menos de 15 segundos; el cuerpo de tu respuesta se ignora. Haz el trabajo después de responder, o ponlo en una cola, para que una tarea lenta no cuente como fallo. Cualquier otra cosa es un intento fallido: otro estado, un tiempo de espera agotado, un error de conexión o de TLS, y una redirección, que no se sigue.
Una entrega fallida se vuelve a intentar al cabo de unos 5 segundos, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas y 14 horas (cada espera varía hasta una décima parte): 8 intentos en unas 31 horas y media, y después se marca como fallida. El lote nunca espera a un webhook. Las entregas se envían en cuanto termina el lote; pueden llegar en otro orden y, en raras ocasiones, el mismo evento puede llegar dos veces, cosa que webhook-id te permite detectar.
Zabio solo envía a direcciones públicas: una dirección cuyo nombre apunta a una red privada o interna se rechaza en cada intento y cuenta como fallida.
Rotar el secreto
Section titled “Rotar el secreto”Rotar secreto crea un secreto nuevo y lo muestra una vez. Durante las 24 horas siguientes cada evento se firma con los dos secretos, dos firmas en webhook-signature, para que puedas desplegar el nuevo sin perder ninguna entrega; después solo firma el nuevo. Si vuelves a rotar dentro de esas 24 horas, se descarta el más antiguo.
Ver las entregas
Section titled “Ver las entregas”Entregas, bajo cada endpoint, muestra sus 50 entregas más recientes: el evento, el lote, el estado (entregado, reintentando con la hora del próximo intento, fallido o cancelado), los intentos y la última respuesta, un código de estado o el tipo de error (timeout, dns, tls, connection, non_public_address). Quitar un endpoint cancela los reintentos pendientes.
Qué se guarda y durante cuánto tiempo
Section titled “Qué se guarda y durante cuánto tiempo”El secreto de firma se guarda cifrado con la clave de tu organización y nunca se muestra después de añadirlo o rotarlo. Cada evento, sus entregas y sus intentos se guardan 30 días. Zabio nunca guarda el cuerpo de tu respuesta y nunca escribe en sus registros el secreto ni la ruta y la consulta de tu dirección.