Webhooks

Webhooks

Los webhooks permiten a tu Board enviar peticiones HTTP a servicios externos siempre que ocurran ciertos eventos durante la producción: se registra una cantidad, se inicia una tarea, se bloquea una tarea, se completa un trabajo, y más. Así es como conectas tu Board a Slack, Microsoft Teams, un ERP, una plataforma de notificaciones, un script personalizado o cualquier otra cosa que pueda recibir una petición HTTP.

Los webhooks viven en Configuración de la aplicación → Webhooks.

Nota: Los Webhooks deben estar habilitados para tu cuenta. Si la página muestra un aviso indicando que los webhooks están deshabilitados, contacta con soporte para activarlos.

---

Tabla de contenido

1. ¿Qué es un webhook?
2. Cuándo usar webhooks
3. Crear un webhook
4. Referencia de campos
5. Eventos a los que puedes suscribirte
6. Referencia de payload
7. Autenticación (API key)
8. Alcance por estación de trabajo
9. Probar un webhook
10. Ejemplos prácticos
11. Logs y resolución de problemas
12. Notas de seguridad

---

¿Qué es un webhook?

Un webhook es una URL que le das a tu Board. Cuando ocurre un evento al que te has suscrito, el Board envía una petición HTTP POST a esa URL con un pequeño payload JSON que describe lo que pasó.

El otro extremo es tu elección — una URL de webhook entrante de Slack, un disparador “Catch Hook” de Zapier, un endpoint en tu propio servidor, una plataforma de automatización, cualquier cosa que pueda recibir HTTP y parsear JSON.

Los webhooks son unidireccionales y dispara-y-olvida — el Board no espera una respuesta significativa, solo registra el código de estado para diagnóstico. Si tu endpoint es lento o está temporalmente caído, el Board no reintenta automáticamente.

---

Cuándo usar webhooks

Algunos casos de uso del mundo real:

• Notificaciones — publica un mensaje en Slack/Teams cuando una tarea se bloquea, se completa un trabajo o comienza una tarea de alta prioridad en una estación de trabajo específica.
• Sincronización ERP / contabilidad — informa a tu sistema de back-office que se han fabricado cantidades para que el inventario y la facturación puedan actualizarse.
• Dashboards personalizados — alimenta un Grafana externo, Looker o dashboard casero con datos de producción en tiempo real.
• Disparar otras automatizaciones — inicia impresión de etiquetas de envío, instrucciones de empaquetado o flujos de control de calidad cuando un trabajo alcanza un estado completado.
• Logs de auditoría / cumplimiento — transmite cada cambio de cantidad o registro de tiempo a un archivo externo.

---

Crear un webhook

1. Ve a Configuración de la aplicación → Webhooks.
2. Rellena el formulario en la parte superior de la página:
   • Origen — qué origen de pedido debe disparar este webhook (o Todos los orígenes).
   • URL del webhook — la URL que expone tu servicio externo.
   • API Key (opcional) — un token de autenticación (consulta Autenticación).
   • Eventos — marca uno o más eventos que quieres recibir.
   • Estaciones de trabajo (opcional) — elige estaciones específicas a las que acotar, o déjalo vacío para disparar en todas las estaciones.
3. Haz clic en Añadir (o Actualizar si editas un webhook existente).

El nuevo webhook aparece en la tabla de abajo. Puedes editarlo en cualquier momento, eliminarlo o enviar una petición de prueba manual.

---

Referencia de campos

Campo	Descripción
Origen	El origen del pedido al que se aplica el webhook. Elige Todos los orígenes para recibir eventos de pedidos desde cualquier origen, o elige una clave de origen específica (manual, shopify, etc.) para disparar solo cuando el pedido del trabajo provino de ese origen.
URL del webhook	La URL HTTPS completa a la que el Board debe hacer POST. Máximo 2000 caracteres.
API Key (opcional)	Si se establece, el Board la envía en cada petición en dos cabeceras — Authorization: Bearer <key> y X-API-Key: <key>. Usa esto si tu endpoint requiere autenticación. Déjalo vacío para endpoints públicos (por ejemplo, webhooks entrantes de Slack).
Eventos	Uno o más eventos que disparan este webhook. Consulta Eventos.
Estaciones de trabajo (opcional)	Una lista de estaciones de trabajo a las que este webhook está acotado. Vacío = dispara en todas las estaciones. Consulta Alcance por estación de trabajo.

---

Eventos a los que puedes suscribirte

Cada webhook se dispara solo para los eventos que hayas marcado. Puedes marcar tantos como quieras.

qty_changed — Cantidad cambiada

Se dispara cada vez que se registra una cantidad contra una estación de trabajo en cualquier trabajo — a través del dashboard, el Kiosk, la aplicación móvil o la API. El payload incluye la estación de trabajo, el total fabricado hasta ahora para el trabajo y campos identificativos sobre el trabajo y el pedido.

Ejemplo de uso: alimentar un sistema ERP en tiempo real con progreso de fabricación.

time_log_saved — Registro de tiempo guardado

Se dispara cuando se crea una entrada de registro de seguimiento de tiempo — ya sea manualmente vía el botón “Submit” del Kiosk, o cuando se detiene un temporizador. El payload incluye la duración en minutos, el empleado, la estación de trabajo, cualquier nota y la cantidad (si la hay) que se registró al mismo tiempo.

Ejemplo de uso: registrar productividad en un sistema de facturación/nóminas.

job_blocked — Tarea bloqueada

Se dispara cuando un empleado marca una tarea como bloqueada (por ejemplo, “material faltante”, “máquina caída”). El payload incluye la nota de bloqueo explicando el motivo.

Ejemplo de uso: publicar una alerta inmediata en Slack para que un supervisor pueda investigar.

job_completed — Tarea completada (trabajo completo)

Se dispara cuando se completa un trabajo entero — es decir, cuando el estado del trabajo pasa al estado de finalización configurado (cambiado manualmente, o automáticamente cuando cada estación de trabajo alcanza su cantidad planificada). El payload incluye la duración total en minutos a través de todas las entradas de seguimiento de tiempo del trabajo.

Ejemplo de uso: disparar un flujo de etiqueta de envío o facturación una vez que un trabajo está totalmente hecho.

task_started — Tarea iniciada en estación de trabajo

Se dispara una vez por estación de trabajo por trabajo, la primera vez que se registra actividad en ella. Actividad significa o bien que se registra la primera cantidad > 0, o bien la primera vez que se inicia un temporizador de seguimiento de tiempo en esa estación de trabajo — lo que ocurra primero. El payload incluye una marca de tiempo ISO started_at.

Ejemplo de uso: notificar a un supervisor que se ha empezado el trabajo en un paso crítico, para que sepa que la producción realmente ha empezado.

task_completed — Tarea completada en estación de trabajo

Se dispara una vez por estación de trabajo por trabajo, la primera vez que esa estación alcanza su cantidad planificada (o para departamentos de cantidad compartida, el momento en que la cantidad agrupada del departamento cumple el total del trabajo). El payload incluye una marca de tiempo ISO completed_at.

Ejemplo de uso: disparar el sistema downstream del siguiente paso (empaquetado, QA, envío) en el momento en que termina una etapa de producción específica.

Idempotencia para task_started / task_completed: cada uno se registra permanentemente en la fila de la estación de trabajo, así que se dispara solo la primera vez que se cumple la condición. Registrar más cantidad o reiniciar un temporizador después del primer disparo no volverá a disparar estos eventos.

---

Referencia de payload

Cada evento envía un objeto JSON vía HTTP POST. Algunos campos son comunes a todos los eventos; otros son específicos del tipo de evento. Los campos vacíos/null se omiten para mantener los payloads compactos.

Campos base (presentes en todos los eventos)

{
    "event": "qty_changed",
    "job_ref": "PB-0042",
    "order_ref": "PO-2025-001",
    "order_external_id": "EXT-12345",
    "manufactured_qty": 7,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "external_id": "ORD-7890",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12
}

Campo	Significado
event	La clave del evento — una de las seis listadas arriba.
job_ref	El número de referencia del trabajo en tu Board.
order_ref	La referencia del pedido padre, si la hay.
order_external_id	El ID externo del pedido (por ejemplo, un ID de pedido de Shopify).
manufactured_qty	Cantidad total fabricada para este trabajo a través de todas las estaciones de trabajo. (Para time_log_saved, este es el total de la estación de trabajo, no del trabajo.)
sku	El SKU del trabajo.
name	El nombre del trabajo.
external_id	El ID externo del trabajo (por ejemplo, el identificador del sistema upstream).
department	Departamento de la estación de trabajo involucrada, si una estación está en contexto.
workstation	Nombre de la estación de trabajo involucrada.
workstation_id	ID numérico de la estación de trabajo involucrada.

Los campos department, workstation y workstation_id están presentes siempre que el evento se relacione con una estación de trabajo específica (así que todos los eventos excepto job_completed, que es a nivel de trabajo completo).

Extras por evento

Evento	Campos adicionales
qty_changed	—
time_log_saved	mode ("manual" o "work_stopped"), log_qty, log_note, duration_minutes, employee (objeto con id, name, surname)
job_blocked	block_note
job_completed	status (nombre del estado de finalización), total_duration_minutes
task_started	started_at (marca de tiempo ISO 8601)
task_completed	completed_at (marca de tiempo ISO 8601)

Ejemplo: payload task_started

{
    "event": "task_started",
    "job_ref": "PB-0042",
    "order_ref": "PO-2025-001",
    "manufactured_qty": 0,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12,
    "started_at": "2026-05-27T08:14:32+00:00"
}

Ejemplo: payload time_log_saved

{
    "event": "time_log_saved",
    "job_ref": "PB-0042",
    "manufactured_qty": 5,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12,
    "mode": "work_stopped",
    "log_qty": 2,
    "log_note": "Two units finished, third in progress",
    "duration_minutes": 47,
    "employee": { "id": 8, "name": "Jan", "surname": "Kowalski" }
}

---

Autenticación (API key)

Si tu endpoint requiere autenticación, rellena el campo API Key. El Board la envía en cada petición en dos cabeceras:

Authorization: Bearer <your-api-key>
X-API-Key: <your-api-key>

La mayoría de los endpoints aceptan cualquiera de las dos formas, así que no importa cuál compruebes en el lado receptor.

Deja API Key vacío para endpoints públicos como los webhooks entrantes de Slack — no esperan ninguna cabecera de autenticación.

---

Alcance por estación de trabajo

Por defecto, un webhook se dispara para cada estación de trabajo. El campo opcional Estaciones de trabajo te permite restringirlo.

Lista vacía (por defecto)

El webhook se dispara para todas las estaciones de trabajo. Este es el comportamiento original — los webhooks existentes creados antes de esta funcionalidad no se ven afectados.

Estaciones de trabajo específicas

El webhook se dispara solo cuando la estación de trabajo del evento está en la lista. Útil cuando:

• Quieres que un canal de Slack reciba alertas solo para las estaciones del equipo de pintura.
• Quieres una integración ERP que solo se preocupe por las estaciones de montaje final.
• Diferentes equipos deberían recibir diferentes notificaciones.

Comportamiento con eventos no de estación de trabajo

El evento job_completed se dispara a nivel de trabajo completo (sin una estación de trabajo específica). Un webhook con una o más estaciones de trabajo seleccionadas no se disparará para job_completed — por diseño. Si quieres que un webhook reciba job_completed, deja la lista de estaciones de trabajo vacía (o crea un segundo webhook solo para ese evento).

Combinado con Origen

El filtro de estación de trabajo se aplica encima del filtro de origen. Un webhook con source=shopify y estaciones de trabajo [A, B] solo se dispara cuando el evento coincide con ambos — un evento de trabajo con origen Shopify ocurriendo en la estación de trabajo A o B.

---

Probar un webhook

La tabla de webhooks tiene un icono de avión de papel (✈) junto a cada fila — haz clic en él para abrir el diálogo de prueba.

1. Elige un evento de los eventos suscritos por tu webhook.
2. Un payload de muestra se renderiza como JSON. Edítalo libremente — cambia cualquier campo para simular un escenario real.
3. Haz clic en Enviar prueba. El diálogo cambia a un panel de resultados mostrando:
   • Código de estado HTTP devuelto por tu endpoint
   • Tiempo tomado (en milisegundos)
   • Cuerpo de respuesta (truncado a 2 KB)
   • Cualquier error de conexión
4. Haz clic en Volver a editar para ajustar el payload y volver a probar.

Esta es la forma más rápida de verificar que tu endpoint es accesible, parsea el payload correctamente y responde con un estado 2xx.

---

Ejemplos prácticos

1. Alerta en Slack cuando cualquier tarea se bloquea

• Origen: Todos los orígenes
• URL: una URL de webhook entrante de Slack
• API Key: vacío
• Eventos: solo job_blocked
• Estaciones de trabajo: vacío

En Slack, el payload llega como JSON; puedes formatearlo bonitamente con un relay (por ejemplo, un Cloudflare Worker que convierte block_note + workstation en un mensaje de Slack). O usa un servicio como Zapier entre los dos para hacer el formateo.

2. Enviar email a un supervisor cuando el taller de pintura termina un trabajo

• Origen: Todos los orígenes
• URL: una URL “Catch Hook” de Zapier conectada a un paso “Send Email” de Gmail
• Eventos: task_completed
• Estaciones de trabajo: marca todas las estaciones del taller de pintura

El webhook se dispara en el momento en que la parte del taller de pintura de cualquier trabajo está hecha. Zapier formatea el email a partir de los campos del payload.

3. Enviar cantidades fabricadas a un ERP

• Origen: un origen externo específico (por ejemplo, shopify)
• URL: el endpoint entrante de tu ERP
• API Key: el token API del ERP
• Eventos: qty_changed, job_completed
• Estaciones de trabajo: vacío (quieres todas)

El ERP recibe un payload después de cada cambio de cantidad más un aviso final de trabajo completo cuando el trabajo está totalmente completo.

4. Diferentes notificaciones por departamento

Crea tres webhooks separados, cada uno acotado a las estaciones de trabajo de su propio departamento:

• “Slack Montaje” → task_started, task_completed, job_blocked, estaciones de trabajo = solo estaciones de montaje
• “Slack Pintura” → mismos eventos, estaciones de trabajo = solo estaciones del taller de pintura
• “Slack Empaquetado” → mismos eventos, estaciones de trabajo = solo estaciones de empaquetado

Cada equipo solo ve las alertas que le importan.

---

Logs y resolución de problemas

Cada petición de webhook — tanto eventos reales como pruebas manuales — se anexa a un log por tenant en el servidor en:

storage/logs/webhooks/webhook_tennent_id_<tenant_id>.log

Cada línea es un objeto JSON con la marca de tiempo, evento, URL, estado HTTP, duración, payload, cuerpo de respuesta y cualquier error. Este es el primer lugar a mirar cuando un webhook parece no estar entregando.

Problemas comunes

• Endpoint devuelve 4xx / 5xx — comprueba el cuerpo de la respuesta en el log. El Board solo deja de enviar en el siguiente evento si la URL se elimina; no reintenta el evento actual automáticamente.
• Ninguna línea de log en absoluto para un evento — tu webhook no está coincidiendo. Verifica los filtros de origen, eventos y estaciones de trabajo. El diálogo de Prueba elude estos filtros y es la forma más rápida de confirmar que la URL funciona.
• Endpoint lento — el timeout de petición del Board es de 10 segundos. Si tu endpoint tarda más, la conexión se cae y se registra un error.
• Errores HTTPS — asegúrate de que tu endpoint tiene un certificado válido. El Board no permite certificados autofirmados.
• Indicador de tenant deshabilitado — la página muestra un aviso deshabilitado si los webhooks están desactivados para tu cuenta. Contacta con soporte.

---

Notas de seguridad

• La propia URL es la credencial cuando no se establece API key. Cualquiera que conozca la URL de un webhook no autenticado (por ejemplo, un webhook entrante de Slack) puede hacer POST a ella. Trata las URLs no autenticadas como secretos y no las compartas públicamente.
• Usa el campo API Key siempre que tu endpoint soporte autenticación. Es una mejora gratuita en seguridad — el Board la envía con cada petición.
• HTTPS es obligatorio para cualquier endpoint que maneje datos reales de producción. El campo URL del webhook también acepta http://, pero úsalo solo para desarrollo local.
• Los payloads incluyen información identificable de pedido/cliente. Asegúrate de que el servicio receptor está aprobado para manejar esos datos — especialmente para orígenes externos, plataformas de automatización de terceros y cualquier servicio que almacene o registre los payloads.
• Los webhooks son por tenant. Los eventos de los datos de un tenant nunca pueden llegar a los webhooks de otro tenant.