Webhooks

Entrega durable

El POS conserva eventos junto a cada cambio de reserva, transferencia, factura y entrega. El conector saliente los lleva al gateway, que los reintenta por HTTPS. Una desconexión demora la notificación; no pierde el evento confirmado. Requiere la migración Commerce de webhooks, conector actualizado y gateway configurado. POS cloud también puede usar este puente; no hay envío directo desde POS.

La entrega puede repetirse o llegar fuera de orden. El evento contiene id, version, integrationId, type, occurredAt y data.checkoutId (referencia externa). No contiene referencias bancarias, datos del comprador ni instrucciones privadas. Consulta un nuevo comando action=status para conocer el estado actual.

Configurar el receptor

El operador añade webhook:{url,secret,enabled:true} a la tienda en COMMERCE_GATEWAY_STORES. URL HTTPS con nombre DNS público IPv4, puerto 443, sin usuario, query ni fragmento. El transporte bloquea redes privadas y redirecciones. secret usa el formato istmo_whk_ seguido de 64 caracteres hexadecimales aleatorios; se guarda únicamente en los secretos de gateway y backend de la tienda.

Guardar destino y secreto es configuración del operador, no un endpoint público. Reiniciar todas las réplicas tras cambios. Sin receptor, eventos quedan disabled y pueden activarse mediante reintento manual. Eventos anteriores a la migración no se generan retroactivamente. No habilitar envíos a un destino sin verificar su propietario.

Verificar antes de procesar

Firma HMAC-SHA256 de timestamp + punto + cuerpo exacto, cabecera x-istmo-signature con prefijo v1=. El cliente valida tolerancia de cinco minutos y comparación constante; mantener reloj sincronizado. No volver a serializar JSON antes de verificar. x-istmo-event-id es informativa: usar el id dentro del cuerpo firmado.

Si falla firma responder 401; si no puede persistir responder 503. Un evento ya persistido puede responder 204. Si status está pendiente por desconexión, reintentar el trabajo interno, no borrar el evento. El receptor no confirma pagos ni emite facturas.

import { verifyCommerceWebhook } from './istmo-commerce.mjs';
const event = verifyCommerceWebhook({
  rawBody, // Buffer de bytes originales, antes del parser JSON
  secret: process.env.ISTMO_WEBHOOK_SECRET,
  timestamp: req.headers['x-istmo-timestamp'],
  signature: req.headers['x-istmo-signature'],
});
// Comprobar integrationId contra la tienda configurada.
// Guardar event.id en una bandeja durable con índice UNIQUE.
// Confirmar esa transacción antes de responder HTTP 204.
// Un trabajador consulta status; eventos repetidos no repiten trabajo.

Diagnóstico y recuperación

GET /webhook-deliveries muestra estado y contador con scope orders:read. POST /webhook-deliveries/{eventId}/retry requiere orders:write y reactiva failed/disabled. Ambas operaciones sólo existen en gateway. Las entregadas devuelven 409 al reintentar. La lista ordena UUID; recorrerla completa para inspección, no guardar el último UUID como cursor de nuevos eventos.

Se intentan hasta ocho envíos por ciclo manual, con timeout de ocho segundos y espera exponencial de hasta una hora. Sólo HTTP 2xx confirma entrega. Un proceso interrumpido recupera trabajos tras la concesión de 60 segundos; puede duplicarse un envío cuya respuesta se perdió. Si cambia el destino, trabajos pendientes del destino anterior quedan failed antes de enviarse y necesitan reintento explícito. Pausar el puente o deshabilitar la tienda detiene nuevos envíos; una petición ya en curso puede terminar.

Respaldar ambas bases. No borrar recibos ni eventos sin una política de retención coordinada con la deduplicación del receptor. No se envían correos ni SMS; estas notificaciones están dirigidas al backend del sitio.