> ## Documentation Index > Fetch the complete documentation index at: https://docs.tread.ai/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks > Suscripciones a eventos en tiempo real — recibe eventos de Tread para Órdenes, Jobs, Cargas, Tickets y registros importados. 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ópico | Qué es | | ----------------- | ------------------------------------------------------------------------------------------------- | | `Order` | Una [Orden](/es/concepts/orders-projects) diaria | | `Job` | La asignación de un [Conductor](/es/concepts/driver-lifecycle) para una Orden | | `Load` | Un ciclo de recogida a descarga | | `Ticket` | El [registro de una carga](/es/concepts/tickets-timesheets) — la prueba de que el trabajo ocurrió | | `ImportedProject` | Un Proyecto enviado por la API de importación | | `ImportedOrder` | Una Orden enviada por la API de importación | | `ImportedTicket` | Un 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: ```json theme={null} { "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 Ve a **Configuración → Integraciones → Webhooks**. Ingresa la URL HTTPS de tu endpoint. Genera o pega un secreto de firma HMAC. Tread incluirá la firma en cada entrega. 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. Si tu endpoint requiere un encabezado de autenticación o un token de enrutamiento, agrégalo en los encabezados de la solicitud. 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 a intervalos crecientes. * Cada evento tiene un límite de reintentos. Una vez alcanzado, la entrega se detiene y la falla queda registrada. * 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](/es/api-reference/introduction) — las formas de los recursos devueltas en el payload * [Agave](/es/integrations/agave) — integración contable para AR/AP