Webhooks

Los webhooks permiten que Scrollengine notifique a sus sistemas externos en tiempo real cuando ocurren eventos. Use webhooks para crear integraciones personalizadas, automatizar flujos de trabajo o sincronizar datos con otras herramientas.

Qué son los webhooks

Un webhook es una solicitud HTTP POST enviada a una URL que usted especifica cada vez que ocurre un evento específico en Scrollengine. Su servidor recibe los datos del evento y puede actuar en consecuencia.

Eventos de webhook disponibles

Evento	Activador
order.created	Se realiza un nuevo pedido de entrega
order.updated	Se modifican los detalles o el estado del pedido
order.delivered	El pedido se marca como entregado
order.cancelled	El pedido se cancela
route.created	Se crea una nueva ruta
route.started	El repartidor inicia una ruta
route.completed	Se completan todas las paradas de una ruta
driver.assigned	Se asigna un repartidor a un pedido o ruta

Configurar un webhook

1. Vaya a Configuración > Integraciones > Webhooks
2. Haga clic en Agregar Webhook
3. Ingrese:
   • URL — El endpoint en su servidor que recibirá el webhook
   • Eventos — Seleccione los eventos a los que desea suscribirse
   • Secreto — Un secreto compartido para verificar la autenticidad del webhook
4. Haga clic en Guardar

Contenido del webhook

Los webhooks se envían como solicitudes HTTP POST con un cuerpo JSON:

{
  "event": "order.delivered",
  "timestamp": "2026-03-13T14:30:00Z",
  "data": {
    "order_id": "12345",
    "shopify_order_id": "98765",
    "delivery_method": "local_delivery",
    "status": "delivered",
    "driver": {
      "id": "d-001",
      "name": "John Driver"
    }
  }
}

Verificar webhooks

Cada webhook incluye un encabezado de firma para verificación:

1. Scrollengine firma el contenido usando su secreto compartido
2. La firma se incluye en el encabezado X-Scrollengine-Signature
3. Su servidor debe verificar la firma antes de procesar

Política de reintentos

Si su endpoint devuelve un código de estado que no es 2xx:

• Scrollengine reintenta hasta 3 veces
• Los reintentos usan retroceso exponencial (1 min, 5 min, 30 min)
• Después de 3 fallos, el webhook se marca como fallido
• Recibirá una notificación para reparar su endpoint

Casos de uso

• Sincronización con ERP — Enviar datos de entrega a su sistema de inventario o contabilidad
• Notificaciones personalizadas — Activar SMS, Slack u otras alertas
• Analíticas — Alimentar eventos de entrega en su plataforma de análisis
• Logística de terceros — Notificar a transportistas o socios externos