Webhooks y integración basada en eventos

Comience con un evento de negocio, como un pedido nuevo o cambiado, un cambio de stock o un cambio en el precio. Defina la acción del propietario de datos y el receptor para cada evento.

Mantenga la carga útil original de la conexión web separada de su modelo normalizado durante un período limitado.

Un nuevo campo opcional no debe romper el análisis de una estructura de eventos conocida.

1. 1

   Constrangir la solicitud

   Acepta sólo los métodos y tipos de contenido requeridos, imponga un límite de tamaño corporal y utilice un corto tiempo de lectura.

2. 2

   Verificar la fuente

   Verifique X-SelSup-Signature con la firma por webhookSecret: HMAC-SHA256 sobre ASCII(t + "." + id + ".") seguido de los bytes de cuerpo crudo. Rechazar sellos de tiempo obsoletos y duplicar ID de entrega.

3. 3

   Permanezca el evento

   Almacenar la carga útil y la clave de deduplicación en una transacción, luego devolver una respuesta exitosa rápidamente.

4. 4

   Proceso sincronizado

   Llame al ERP, WMS y otros sistemas desde una cola en lugar de la solicitud de HTTP entrante.

const crypto = require('node:crypto');
const signingSecret = process.env.SELSUP_WEBHOOK_SECRET;

// Register this route before express.json() so req.body is a Buffer.
app.post('/selsup/events', express.raw({type: 'application/json'}), async (req, res) => {
  const header = req.get('X-SelSup-Signature') || '';
  const match = /^t=(\d+),id=([0-9a-f-]{36}),v1=([0-9a-f]{64})$/.exec(header);
  if (!match) return res.sendStatus(401);
  const [, timestamp, deliveryId, hex] = match;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(401);
  const signed = Buffer.concat([
    Buffer.from(`${timestamp}.${deliveryId}.`, 'ascii'), req.body
  ]);
  const expected = crypto.createHmac('sha256', Buffer.from(signingSecret, 'hex'))
    .update(signed).digest();
  const actual = Buffer.from(hex, 'hex');
  if (actual.length !== expected.length || !crypto.timingSafeEqual(actual, expected)) {
    return res.sendStatus(401);
  }
  const inserted = await inbox.insertOnce(deliveryId, req.body);
  return res.sendStatus(inserted ? 202 : 200);
});

Trate la entrega de duplicados como normal. Utilice un identificador de evento estable cuando esté presente; de lo contrario, deriva una clave del tipo de entidad, el id de la entidad y el tiempo de modificación.

Los eventos pueden llegar fuera de orden. Comparar modificadoDate antes de escribir o recargar la entidad actual a través de API.

Regresa el estado de éxito de un evento ya procesado. De lo contrario, el remitente puede continuar intentando el trabajo terminado.

Ejecutar la reconciliación periódica API incluso cuando los webhooks están sanos. Utilice modificadoDate con superposición para pedidos y un almacén o cambio de SKU para el inventario.

Después de la falta de tiempo del receptor, agota la bandeja de entrada y solicita cambios para la ventana de apagón completa. La misma lógica de deduplicación debe combinar los resultados webhook y API.

Exponer la URL activa, el tipo de evento, el último recibo exitoso y el último error en su integración. Esto permite el diagnóstico sin acceso directo al registro del servidor.

Antes de reemplazar o eliminar una URL, compruebe si el nuevo receptor acepta eventos.