Manual de integración — Webhooks de estado de pedidos

Este manual está dirigido al equipo técnico del integrador (plataforma multi-tienda, CRM, e-commerce, ERP o sistema propio del negocio) que recibe notificaciones de GSG cuando un pedido registrado vía la API de integración cambia de estado logístico. Aquí está todo lo necesario para recibir, verificar y procesar esos eventos correctamente.

1.Novedades de esta versión (1.2)

El payload incorpora cuatro campos aditivos dentro de data: state_id, route_type_code, size_code y service. Con ellos tu sistema sabe, sin consultar el pedido, qué estado numérico se aplicó y qué tipo de envío y servicio (courier o GSG XL) era. event_version se mantiene en 1.0: la política del contrato es aditiva.

Además, el manual cubre el nuevo escenario de integración directa: el negocio con sistema propio configura su propio webhook desde el panel GSG (sección 3).

Revisión del mismo día (2026-09-03): una respuesta 3xx de tu endpoint ya no se reintenta (el evento queda retenido de inmediato, sección 9); los estados DRIVER_ASIGNADO y DRIVER_DESASIGNADO ahora también generan evento; previous_status es null (no la cadena "null") cuando no hay estado previo; route_state_id viaja en todos los caminos de cambio de estado; y los eventos generados mientras el vínculo de la tienda no estaba activo quedan retenidos en GSG y pueden liberarse al reactivarlo (sección 9).

2.Cómo funciona

Cada vez que un pedido tuyo (creado vía POST /api/v1/orders/integration) cambia de estado — asignado, en ruta, entregado, cancelado, etc. — GSG envía un POST JSON a tu URL de webhook. La entrega es asíncrona, con reintentos automáticos, y cada evento va firmado con HMAC-SHA256 usando el webhook_secret que obtuviste al configurar el webhook.

3.Dónde se configura el webhook

• La URL debe ser HTTPS y apuntar a un host público (no localhost ni redes privadas), sin credenciales embebidas, máximo 500 caracteres.
• Eventos soportados hoy: route.status_changed. Si no indicas suscripción, recibes todos los soportados.
• GET /api/v1/integration/me devuelve el estado de tu webhook (configured, is_active, url_masked, last_delivery_at) para verificar la configuración desde tu backend (solo integración directa; para plataformas es null).
• Los eventos se generan por cada cambio de estado del catálogo, incluidos DRIVER_ASIGNADO (6) y DRIVER_DESASIGNADO (18).

4.Requisitos de tu endpoint

• Aceptar POST con Content-Type: application/json por HTTPS en un host público (no se aceptan URLs http://, localhost ni redes privadas).
• Responder 2xx en menos de 10 s en la misma URL registrada: GSG no sigue redirecciones; un 3xx deja el evento retenido de inmediato (sin reintentos) con el motivo Redirección <status> a <location>: GSG no sigue redirecciones; registre la URL final. Registra la URL final (https, sin barra final que redirija, dominio canónico). Si tu procesamiento es pesado, encola y responde primero.
• Verificar la firma antes de confiar en el contenido (sección 6).
• Deduplicar por event_id: el mismo evento puede llegar más de una vez.
• Tolerar campos desconocidos en el JSON: GSG agrega campos de forma aditiva sin cambiar la versión del evento.

5.Cabeceras HTTP

6.Verificación de la firma

Lee el cuerpo como texto crudo (sin re-serializar el JSON), calcula el HMAC-SHA256 con tu secret y compara en tiempo constante con el valor que sigue a sha256=. Si no coincide, responde 401 y descarta.

Node.js (Express)

import { createHmac, timingSafeEqual } from "node:crypto";

app.post("/webhooks/gsg", express.raw({ type: "application/json" }), (req, res) => {
  const firma = req.get("X-GSG-Signature") || "";
  const esperada = "sha256=" +
    createHmac("sha256", process.env.GSG_WEBHOOK_SECRET)
      .update(req.body)            // Buffer del cuerpo EXACTO recibido
      .digest("hex");

  const a = Buffer.from(firma), b = Buffer.from(esperada);
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return res.status(401).end();
  }

  const evento = JSON.parse(req.body.toString("utf8"));
  res.status(200).end();           // responde rápido…
  procesarEvento(evento);          // …y procesa después
});

PHP

$body   = file_get_contents('php://input');
$firma  = $_SERVER['HTTP_X_GSG_SIGNATURE'] ?? '';
$secret = getenv('GSG_WEBHOOK_SECRET');

$esperada = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($esperada, $firma)) {
    http_response_code(401);
    exit;
}

$evento = json_decode($body, true);
http_response_code(200);
// procesar $evento (idealmente en una cola)

7.Payload del evento

{
  "event_id": "<uuid-v4>",
  "event_type": "route.status_changed",
  "event_version": "1.0",
  "occurred_at": "<ISO-8601>",
  "data": {
    "integration_client_code": "<tu código de integración>",
    "binding_id": 123,
    "store_token_ref": "st_…xxxxxx",
    "business_id": 456,
    "external_store_id": "tu-id-de-tienda",
    "route_id": 789,
    "tracking_code": "GSG-E-789",
    "order_external_id": "tu-id-de-pedido",
    "previous_status": "EN_RUTA",
    "new_status": "ENTREGADO",
    "status_changed_at": "<ISO-8601>",
    "route_state_id": 888994,
    "reported_at": "<ISO-8601 | null>",
    "received_at": "<ISO-8601>",
    "state_id": 14,
    "route_type_code": "DELIVERY",
    "size_code": "M",
    "service": "COURIER"
  }
}

8.Orden de eventos y reportes offline

Los motorizados pueden operar en zonas sin cobertura: sus reportes se guardan en el teléfono y se sincronizan en ráfaga al recuperar señal. Sumado a los reintentos con backoff, esto significa que puedes recibir los webhooks de un mismo envío fuera de orden (por ejemplo: EN_RUTA, luego ENTREGADO, y al final un EN_EL_PUNTO rezagado).

// pseudocódigo
ultimo = estadoPorRuta[evento.data.route_id] ?? 0

si (evento.data.route_state_id != null && evento.data.route_state_id <= ultimo) {
    // evento rezagado o duplicado → confirmar con 2xx y no aplicar
    return 200
}

aplicarCambioDeEstado(evento.data)
estadoPorRuta[evento.data.route_id] = evento.data.route_state_id
return 200

Si te interesa mostrar la hora real de la entrega (y no la hora de sincronización), usa reported_at cuando no sea null.

9.Reintentos y reenvíos

Ningún evento se pierde: si tu servidor estuvo caído, el equipo de GSG puede liberar los eventos retenidos cuando vuelvas a estar operativo (los reenvíos usan la URL y el secret actuales de tu webhook). Esos reenvíos llegan con el mismo event_id original — otra razón por la que la deduplicación es obligatoria. Mientras tanto, puedes reconciliar con la consulta por API.

10.Buenas prácticas obligatorias

1. Responde 2xx rápido y procesa en segundo plano. Un timeout cuenta como fallo y consume reintentos.
2. Deduplica por event_id: reintentos y reenvíos entregan el mismo evento más de una vez.
3. Ordena por route_state_id, nunca por hora de llegada ni por status_changed_at.
4. Ignora campos que no conozcas: el contrato crece de forma aditiva. No valides con additionalProperties: false.
5. Guarda el webhook_secret como credencial (vault/variables de entorno). Si sospechas que se filtró, rótalo (integración directa: desde tu panel; plataforma: pídelo a GSG).
6. Responde 2xx también a los eventos que decidas ignorar (viejos, duplicados, tipos que no te interesan). Un 4xx/5xx provoca reintentos inútiles.
7. Usa el webhook como fuente principal y el polling como respaldo (cada 15 min sobre pedidos no finales) para cubrir ventanas en que no pudiste recibir eventos.

11.Errores frecuentes

12.Historial de cambios