Ir al contenido
Zabio está en beta: los modelos, los precios y las funciones pueden cambiar. Cuéntanos qué falla en hello@zabio.ai.

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.

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.

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.

POST /tu/ruta HTTP/1.1
Content-Type: application/json
User-Agent: Zabio-Webhooks/1.0
webhook-id: evt_019a6d1c7e2b7f3c8a9d0e1f2a3b4c5d
webhook-timestamp: 1762646400
webhook-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-id es el id del evento. Es el mismo en cada reintento, así que úsalo para ignorar una entrega que ya procesaste.
  • webhook-timestamp es cuándo se envió este intento, en segundos Unix. Cada reintento tiene uno nuevo.
  • webhook-signature es v1, y el HMAC-SHA256 en base64, con tu secreto como key, de webhook-id, un punto, webhook-timestamp, un punto y el cuerpo tal cual. Durante una rotación hay dos firmas separadas por un espacio.

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 False

Node.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).

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 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.

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.

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.