Saltar al contenido principal
Los webhooks envían eventos en tiempo real desde Tread a una URL que tú controlas. Usa webhooks cuando tu sistema downstream (data warehouse, ERP, dashboard personalizado) necesite reaccionar en el momento en que algo ocurre en Tread — se crea una orden, se aprueba un ticket, se actualiza un proyecto — en lugar de hacer polling a la API.

​
Requisitos previos

  • Un endpoint HTTPS que tú controles. HTTP es rechazado.
  • Un usuario administrador de Tread con el permiso Integraciones.
  • Capacidad para verificar firmas HMAC en el lado receptor.
  • Un manejador tolerante a reintentos. Tread reintenta las entregas fallidas.

​
Cómo funciona

  1. Registrar una suscripción — Configura la URL de destino, el secreto de firma HMAC y cualquier encabezado personalizado en Configuración → Integraciones → Webhooks.
  2. Elegir disparadores — Cada suscripción escucha uno o más disparadores. Un disparador es un tópico más un evento (por ejemplo, Order::create).
  3. Tread dispara eventos — Cuando ocurre una acción que coincide en la app, Tread construye un envelope JSON y lo envía vía POST a tu URL.
  4. Verificar la firma — Tread firma el cuerpo con HMAC-SHA256 usando tu secreto. La firma llega en el encabezado X-Tread-Hmac-sha256.
  5. Confirmar con 2xx — Una respuesta 2xx marca el evento como entregado. Cualquier otra cosa dispara un reintento.

​
Tópicos y tipos de eventos

Tread emite eventos en estos tópicos:
TópicoQué es
OrderUna orden diaria
JobLa asignación de un conductor para una orden
LoadUn ciclo de recogida a descarga
TicketUn ticket de báscula o de horas de conductor
ImportedProjectUn proyecto enviado por la API de importación
ImportedOrderUna orden enviada por la API de importación
ImportedTicketUn ticket enviado por la API de importación
Cada tópico admite estos tipos de evento: create, update, state_change, skip, error. Suscríbete a las combinaciones que te interesen.

​
Formato del payload

Cada entrega tiene el mismo envelope: 
{
  "subscription_id": "uuid",
  "trigger_id": "uuid",
  "event_id": "uuid",
  "delivery_id": "uuid",
  "attempt": 1,
  "event_time": "2026-04-30T14:21:09Z",
  "event": "Order::create",
  "payload": { },
  "meta": {
    "company_id": "uuid"
  }
}
El campo payload contiene el recurso tal como aparece en la API de Tread. El campo event es el tópico y el tipo de evento unidos por ::. El campo attempt comienza en 1 y se incrementa en cada reintento.

​
Configuración

1

Abre la configuración de Webhooks

Ve a Configuración → Integraciones → Webhooks.
2

Agrega una suscripción

Ingresa la URL HTTPS de tu endpoint. Genera o pega un secreto de firma HMAC. Tread incluirá la firma en cada entrega.
3

Elige disparadores

Selecciona las combinaciones de tópico y evento que quieras. Empieza acotado — Order::create y Ticket::state_change cubren la mayoría de los casos de uso.
4

Agrega encabezados personalizados (opcional)

Si tu endpoint requiere un encabezado de autenticación o un token de enrutamiento, agrégalo en los encabezados de la solicitud.
5

Envía un evento de prueba

Usa el botón Enviar prueba para confirmar que tu endpoint reciba, verifique y confirme. Inspecciona el log de entrega para ver el código de respuesta.

​
Verificación de firma

Para cada entrega, Tread calcula: 
HMAC-SHA256(secret, request_body) → hex digest
El digest se envía en el encabezado X-Tread-Hmac-sha256. Recalcula en tu lado usando el cuerpo de la solicitud sin procesar y compáralos. Rechaza cualquier solicitud cuya firma no coincida.

​
Comportamiento de reintentos

  • Las entregas fallidas (respuesta distinta de 2xx, timeout, redirect) se reintentan con backoff exponencial.
  • Cada suscripción tiene un límite de reintentos configurable. Una vez alcanzado, el evento se descarta y se registra.
  • El campo attempt del envelope indica qué reintento estás viendo.
  • El timeout de entrega es de 10 segundos. Confirma rápido y procesa de forma asíncrona.

​
Limitaciones

  • Solo HTTPS. Las URLs HTTP son rechazadas al registrarse.
  • Una URL de destino por suscripción. Para hacer fan-out, registra múltiples suscripciones.
  • Timeout de entrega de 10 segundos. Los manejadores de larga duración deben responder primero y procesar en segundo plano.
  • Tread no garantiza el orden de los eventos. Usa event_time para reconciliar.
  • Las repeticiones (replays) no son compatibles. Una vez que una entrega agota los reintentos, se pierde — diseña para entrega al-menos-una-vez y manejadores idempotentes.

​
Solución de problemas

Firma no coincide
  1. Confirma que estás hasheando el cuerpo de la solicitud sin procesar, no una copia parseada.
  2. Confirma que estás usando el mismo cifrado HMAC (por defecto: SHA-256).
  3. Rota el secreto si pudo haberse filtrado.
El endpoint se queda sin tiempo
  1. Reduce el trabajo del manejador — confirma inmediatamente y encola el procesamiento real.
  2. Revisa el log de entrega para ver el tiempo de respuesta.
Los eventos no se disparan
  1. Confirma que la suscripción tenga el disparador correcto (tópico + evento).
  2. Confirma que la acción en Tread coincida con el tópico. Order::create se dispara al crear una orden, no al actualizarla — agrega Order::update por separado.

​
Relacionado

  • Referencia de API — las formas de los recursos devueltas en el payload
  • Agave — integración contable; complementa los webhooks para el envío de AR/AP