Webhooks salientes

Los webhooks permiten que FreeMaint haga un POST a una URL que usted controla en cuanto ocurre algo, de modo que otro sistema (ERP, facturación, inventario, contabilidad, un canal de chat) se mantenga al día sin que nadie vuelva a teclear los datos. Se configuran en /company-settings/webhooks. Starter está limitado a 100 entregas/día; Business y superiores son ilimitados. Para la referencia completa de las cargas útiles, consulte API & GraphQL > Webhooks.

Eventos disponibles

• work_order.created — se creó una orden de trabajo
• work_order.completed — una orden de trabajo pasó a Completada
• work_order.status_changed — una orden de trabajo cambió a cualquier estado; work_order.completed se sigue enviando también
• request.created — se envió una solicitud de mantenimiento
• request.status_changed — una solicitud fue aprobada, rechazada o cancelada
• part.low_stock — un repuesto bajó hasta o por debajo de su punto de pedido
• part.out_of_stock — un repuesto llegó a cero
• part.low_stock_summary — una vez al día, los repuestos en su punto de pedido o por debajo, incluidos los que nunca se movieron
• part.out_of_stock_summary — una vez al día, los repuestos que están a cero
• part.consumed — consumido en una orden de trabajo o devuelto de ella
• compliance.chain_divergence — se rompió la cadena de hash de auditoría (Enterprise)
• asset.downtime_started — se abrió una parada de máquina
• asset.downtime_ended — se cerró una parada de máquina
• report.daily_summary — los trabajos completados del día, una vez al día a la hora que elija
• purchase_order.created — se creó una orden de compra
• purchase_order.status_changed — una orden de compra cambió de estado (aprobada, pedida, cancelada…)
• purchase_order.received — se recibió una entrega de una orden de compra, incluidas las parciales

Semántica de entrega

• POST con cuerpo JSON: { event, timestamp, data }
• Cabecera X-FreeMaint-Signature — t=<segundos unix>,v1=<hex>, donde v1 es el HMAC-SHA256 de «<t>.<cuerpo en bruto>» usando como clave el secreto de su webhook. Verifíquela en cada petición, sobre el cuerpo en bruto
• También se envían X-FreeMaint-Event y X-FreeMaint-Delivery-Id
• Los errores de red y los 5xx se reintentan hasta 3 veces con retroceso exponencial (unos 2 s, 4 s, 8 s); un 4xx es un rechazo definitivo y no se reintenta
• Cada intento queda registrado bajo el webhook con su estado, código de respuesta y número de intentos — y cualquier entrega finalizada puede reenviarse desde ahí
• Fotos opcionales: con «Incluir fotos» activado, los eventos "work_order" y "request" incluyen hasta 4 enlaces de imágenes en un campo "photos", válidos 7 días para cualquier persona que los tenga; actívelo solo para un endpoint que usted controle

Configuración

1. Abrir /company-settings/webhooks — Requiere el permiso de configuración de la empresa o el permiso «Gestionar integraciones».
2. Pulsar «Añadir webhook» — Póngale un nombre, una URL https:// y marque los eventos que quiera.
3. Copiar el secreto de firma — Se muestra UNA sola vez al crearlo. Después puede generar otro con «Rotar secreto», lo que invalida el anterior.
4. Vigilar las entregas — Abra el historial de entregas del webhook para confirmar que llegan los eventos y reenviar lo que haya fallado.

Límites por plan

• Starter — 100 entregas/día por empresa (el contador se reinicia a las 00:00 UTC)
• Business — ilimitado
• Enterprise — ilimitado
• El contador cuenta INTENTOS: tres webhooks sobre el mismo evento consumen tres unidades