Webhooks
Envía los eventos de Bitelio a tu propio servidor en cuanto ocurren
Un webhook es una petición HTTP POST que Bitelio envía a una URL que tú controlas cada vez que ocurre algo en tu proyecto: un correo entregado, un contacto que se suscribe, un pedido de Shopify que llega. Es la alternativa a consultar la API por sondeo (polling): en lugar de preguntar "¿ha pasado algo?" a intervalos, tu servidor recibe el aviso en el mismo instante en que ocurre.
No es lo mismo que un paso Webhook de flujo de trabajo
Bitelio tiene una segunda forma, más antigua, de enviar una petición HTTP: un paso Webhook dentro de un flujo de trabajo, configurado por flujo de trabajo con su propia URL, cabeceras y cuerpo. No lleva firma, no tiene historial de entregas, reenvío ni disyuntor de circuito, y sus reintentos a nivel de cola solo cubren el paso en el que reentra un job reintentado — no el resto de la cadena. Esta sección documenta las suscripciones de endpoint que se registran en Ajustes → Webhooks: cada petición se firma, se reintenta y es consultable, con degradación automática para un endpoint que sigue fallando. Usa el que mejor encaje — o los dos.
Registrar un endpoint
Ve a Ajustes → Webhooks y añade un endpoint:
- Una URL HTTPS — el HTTP simple se rechaza. Un payload de webhook puede contener datos de contacto, así que la conexión debe ir cifrada.
- Los eventos que quieres recibir, elegidos del catálogo que muestra el formulario (por ejemplo,
email.delivery,contact.subscribed,shopify.order.paid). - Una descripción opcional, para distinguir endpoints más adelante.
Al guardar se devuelve un secreto de firma (whsec_...), que se muestra una sola vez en texto plano y nunca más — cópialo directamente al lugar donde tu receptor lee su configuración. Solo volverás a verlo si lo rotas, lo que emite uno nuevo manteniendo el anterior válido durante 24 horas, para que puedas migrar tu receptor al nuevo secreto sin perder eventos mientras tanto.
Una vez guardado el endpoint, usa Enviar evento de prueba para confirmar que tu receptor responde correctamente antes de confiar en él. Un evento de prueba recorre exactamente el mismo camino de firma, entrega y reintentos que uno real — solo que lleva un tipo de evento fijo, bitelio.webhook.test, en lugar de uno real.
Qué recibes
Cada evento llega como un POST con un cuerpo JSON con esta forma:
{
"id": "b0f6b8b0-6e0a-4f0a-9c0a-4e2b9b7b8a10",
"type": "email.delivery",
"occurredAt": "2026-07-30T12:00:00.000Z",
"contactId": "1f9d1a3c-9b0a-4b8a-9c1a-0a1b2c3d4e5f",
"data": {}
}data lleva el detalle específico de ese tipo de evento — su forma no es fija entre eventos, ya que refleja lo que Bitelio registra internamente para ese evento.
Junto al cuerpo llegan cinco cabeceras propias — Bitelio-Signature, Bitelio-Timestamp, Bitelio-Idempotency-Id, Bitelio-Event-Type y Bitelio-Schema-Version — que se explican en la siguiente página.
En esta sección
| Página | Cubre |
|---|---|
| Verificar firmas | Confirmar que una petición viene realmente de Bitelio, con un ejemplo en Node ejecutable |
| Garantías de entrega | Entrega al menos una vez y sin orden garantizado: el calendario de reintentos, la degradación, la retención y el reenvío |