Webhooks

Los webhooks reciben eventos en tiempo real mediante HTTP POST a una URL que configuras tú. Los mismos eventos también están disponibles mediante SSE. Los webhooks se configuran por organización: cada organización tiene los suyos.

GestiónCopiar el enlace a esta sección

Consulta la especificación OpenAPI para los esquemas completos de petición y respuesta.

Crear un webhookCopiar el enlace a esta sección

POST /api/orgs/org_abc123/webhooks
Content-Type: application/json
x-api-key: tkn_xxx

{
  "url": "https://jouw-server.com/webhooks/tillor",
  "subscribedEventKeys": ["invoice:created", "invoice:paid", "customer:updated"],
  "enabled": true
}

• url - Endpoint HTTPS que acepta peticiones POST
• subscribedEventKeys - Array de claves de evento o ["*"] para todos los eventos. La lista completa está en Tillor en Menú de perfil → Desarrolladores, en Añadir webhook → Eventos suscritos.

Algunos eventos son tan frecuentes que no puedes elegirlos y tampoco llegan mediante *, como el estado físico de las barreras, la escritura en la bandeja de entrada, los logs del controlador y la presencia de vehículos. No aparecen en la lista de abajo. Qué eventos puedes elegir depende también de tus permisos.

• enabled - true para activar la entrega

Solo puedes elegir eventos para los que tu miembro de la organización tenga el permiso adecuado (p. ej. transacciones bancarias para bankAccountTransaction:*). El comodín * solo está disponible para miembros con acceso total (*). Con una combinación no válida, la API devuelve un mensaje de error. Un webhook envía el payload completo, con los datos vinculados (como el cliente en una reserva). Por eso también debes poder leer esos dominios para crear un webhook, cambiar la URL o los eventos, o volver a activarlo.

Payload del webhookCopiar el enlace a esta sección

Cada entrega de webhook es un POST con:

Encabezados:

• Content-Type: application/json
• X-Webhook-Event-ID - ID único y estable de esta entrega lógica (mismo valor en los reintentos)
• X-Webhook-Signature - firma HMAC-SHA256 del body, formato sha256=<hex> (consulta Verificar la firma)

Body:

{
  "event": "invoice:created",
  "data": {},
  "timestamp": 1735689600000,
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spanId": "00f067aa0ba902b7",
  "triggeredBy": {
    "id": "usr_63x8jp68is",
    "name": "Niels"
  }
}

Consulta Ejemplos para ver ejemplos completos de payload.

Verificar la firmaCopiar el enlace a esta sección

Cada webhook tiene su propio secreto de firma (64 caracteres hexadecimales, visible en la tabla de webhooks mediante Mostrar secreto de firma en Menú de perfil → Desarrolladores). Tillor firma cada POST con ese secreto para que puedas comprobar que la petición viene realmente de Tillor y que el body no se ha modificado.

Cómo firma Tillor:

1. Calcula HMAC-SHA256(signingSecret, raw_request_body) (hex en minúsculas).
2. Lo envía como X-Webhook-Signature: sha256=<hex>.

Cómo verificas tú:

1. Lee el body en bruto de la petición (antes de analizar el JSON; si no, el hash no coincidirá).
2. Calcula tú mismo HMAC-SHA256(signingSecret, raw_body) en hex.
3. Compara con el valor que sigue a sha256= en el encabezado X-Webhook-Signature con una comparación de tiempo constante.

import crypto from "node:crypto";

function verifyTillorWebhook(rawBody, headerSignature, signingSecret) {
  const expected = crypto.createHmac("sha256", signingSecret).update(rawBody).digest("hex");
  const received = headerSignature.replace(/^sha256=/, "");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Comportamiento de entrega y reintentosCopiar el enlace a esta sección

• Responde con un estado 2xx para confirmar el éxito.
• Si una entrega falla (no 2xx, error de red o destino bloqueado), Tillor la reintenta automáticamente con intervalos cada vez más largos. Cada intento reutiliza el mismo payload, la misma firma y el mismo ID de evento (idempotente).

• Si uno de los intentos tiene éxito (2xx) → la entrega queda completada.
• Si tampoco tiene éxito el intento 10 (tras 24 h) → la entrega se marca definitivamente como fallida y no se reintenta más.
• Si mientras tanto el webhook se desactiva, Tillor deja de reintentar.

Avisos por fallos persistentesCopiar el enlace a esta sección

Si las entregas a un endpoint de webhook siguen fallando, Tillor envía como máximo dos avisos por incidente (por endpoint):

1. Tras 5 minutos de fallos persistentes - correo electrónico a la dirección de correo de la organización (supportEmail, o si no email) y a los miembros de la organización con permiso para modificar los ajustes de la organización, además de una notificación push (si está activada) para esos miembros. El correo indica desde cuándo fallan las entregas. Las fechas del correo usan la zona horaria de Configuración > General (por defecto Europe/Brussels).
2. Al fallar definitivamente - los mismos destinatarios reciben un aviso cuando el primer evento de ese incidente se marca como fallido de forma definitiva tras todos los intentos.

No recibes un aviso por cada evento fallido. En cuanto todas las entregas fallidas de un endpoint se resuelven (entregadas con éxito), un nuevo incidente empieza de nuevo con las mismas reglas.

En Menú de perfil → Desarrolladores, la tabla de webhooks muestra por endpoint un estado de entrega compacto (cantidades pendientes de reintento y fallidas de forma definitiva). Haz clic en el icono ℹ para ver los detalles, incluido el mensaje de error completo y el payload del intento más reciente.

• Reintentar entregas fallidas (↻): solo las entregas fallidas de forma definitiva de ese webhook.
• Forzar reintento (⚡): todas las entregas pendientes y fallidas de forma definitiva de ese webhook, independientemente de los tiempos de espera programados. Tillor lo inicia en segundo plano para que las colas grandes (p. ej. miles de eventos) se procesen con seguridad.
• Forzar reintento de todos, arriba a la derecha junto a Añadir webhook: lo mismo para todos los webhooks activados de la organización.

Tipos de eventoCopiar el enlace a esta sección

Las claves de evento usan el formato entity:action o entity:subresource:action. La lista completa, con el permiso de cada evento y un ejemplo de payload, está en el índice de eventos. Esa página se genera a partir del código y por tanto siempre está completa. Las mismas claves están en Tillor en Menú de perfil → Desarrolladores, en Añadir webhook → Eventos suscritos.

Webhooks frente a SSECopiar el enlace a esta sección

RelacionadoCopiar el enlace a esta sección

• OpenAPI - especificación completa de la API
• API HTTP - API REST y claves de API
• SSE - los mismos eventos mediante Server-Sent Events
• Automatizaciones - enviar mensajes propios desde una automatización