Webhooks
Envía datos automáticamente a otras aplicaciones cuando ocurren cosas en tu cuenta.
Descripción General
Los webhooks te permiten enviar datos automáticamente a otras aplicaciones o servicios cada vez que algo ocurre en tu cuenta — por ejemplo, cuando se crea una nueva Order, se paga una factura o se publica un Report. En lugar de revisar tu panel manualmente, los webhooks envían las actualizaciones a tus herramientas en tiempo real.
Gestiona tus webhooks en ConfiguraciónIntegraciones.
Configurar un Endpoint de Webhook
Navega a Integraciones
Ve a ConfiguraciónIntegraciones y desplázate hacia abajo hasta la sección Webhooks.
Agrega un Endpoint
Haz clic en Agregar endpoint. En el cuadro de diálogo que aparece, ingresa:
| Campo | Descripción |
|---|---|
| URL | La dirección web donde quieres recibir los datos (proporcionada por la aplicación o servicio que estás conectando) |
| Descripción | Una etiqueta opcional para ayudarte a recordar para qué sirve este endpoint |
| Eventos | Elige qué eventos deben activar una notificación — puedes seleccionar eventos individuales o suscribirte a todos |
Crea y Copia el Secreto de Firma
Haz clic en Crear. Aparecerá un secreto de firma — es una clave de seguridad que permite a la aplicación receptora verificar que los datos provienen de tu cuenta.
Copia tu secreto ahora
El secreto de firma solo se muestra una vez. Cópialo y guárdalo en un lugar seguro. Si lo pierdes, necesitarás rotar el secreto desde la configuración del endpoint.
Puedes agregar hasta 10 endpoints de webhook por cuenta.
Eventos Disponibles
Estos eventos se entregan hoy:
| Evento | Qué lo activa |
|---|---|
| Orden creada | Se agrega una nueva Order a tu cuenta |
| Orden aprobada | Se aprueba una Order |
| Orden completada | Se marca una Order como completa |
| Orden reprogramada | Se cambia la fecha/hora de la cita de una Order aprobada |
| Estado de orden cambiado | Una Order se aprueba, se completa o se cancela su aprobación |
| Factura pagada | Se marca una factura como pagada — en línea o registrada manualmente |
| Reporte publicado | Se publica un Report |
El formulario del endpoint también lista Orden actualizada, Factura creada, Contacto creado y Contacto actualizado. Puedes suscribirte a ellos ahora, pero todavía no se envían — están reservados para entregas futuras.
Consulta Eventos de Webhook para ver el payload exacto de cada evento.
Nombres de eventos y campos estables
Los nombres de los eventos y de los campos del payload son los mismos para todas las cuentas e industrias, así que tu integración sigue funcionando si cambias tu configuración de industria. Algunos campos del payload usan nombres heredados (por ejemplo inspectionType para la categoría de servicio) — consulta la referencia de eventos.
Probar tu Webhook
Después de crear un endpoint, puedes enviar un evento de prueba para asegurarte de que todo esté conectado:
Busca tu endpoint en la lista y haz clic en el botón de menú.
Selecciona Send test event. Se enviará un evento de muestra a la URL de tu endpoint.
Revisa tu aplicación receptora para confirmar que los datos de prueba llegaron.
Solución de Problemas
Endpoint Deshabilitado
Si tu endpoint falla en recibir datos 8 veces seguidas, se deshabilita automáticamente para evitar fallos repetidos. El endpoint mostrará un estado de Desactivado.
Para volver a habilitarlo:
- Corrige el problema del lado receptor (asegúrate de que la URL sea accesible y responda correctamente).
- Haz clic en el botón de menú del endpoint y selecciona Enable.
Revisar el Historial de Entregas
Haz clic en el botón de menú de cualquier endpoint y selecciona View deliveries para ver un registro de los intentos de entrega recientes. Cada entrada muestra:
- Si la entrega tuvo éxito o falló
- El código de respuesta HTTP
- Cuándo se envió
Esto te ayuda a identificar qué salió mal si los eventos no están llegando como esperas.
Seguridad
Cada entrega de webhook incluye una firma en los encabezados de la solicitud. Si trabajas con un desarrollador para crear una integración personalizada, puede usar tu secreto de firma para verificar que los datos entrantes realmente provienen de tu cuenta de ITB y no han sido alterados.
Los encabezados relevantes son:
| Encabezado | Propósito |
|---|---|
webhook-id | Un ID único para este evento |
webhook-timestamp | Cuándo se envió el evento (marca de tiempo Unix) |
webhook-signature | La firma HMAC-SHA256 a verificar |
Para desarrolladores
Para verificar una firma, calcula HMAC-SHA256 sobre la cadena {timestamp}.{body} usando tu secreto de firma, y compárala con la firma del encabezado (después de quitar el prefijo v1=). Usa una comparación de tiempo constante para prevenir ataques de temporización.
Uso con Zapier y Make
Si usas plataformas de automatización como Zapier o Make (antes Integromat), pueden conectarse a tu cuenta de ITB mediante OAuth y suscribirse a eventos de webhook automáticamente. Busca la integración de ITB en el directorio de aplicaciones de tu plataforma de automatización.