Firma HMAC

Cada evento webhook incluye una firma criptográfica. Tu ERP debe validarla antes de procesar el evento — esto garantiza que el request viene de OrderFast y que el body no fue alterado en tránsito.

El mecanismo de firma es idéntico al de v1.

Headers del request

OrderFast envía estos headers en cada entrega:

X-OrderFast-Event-Id: evt_01J...
X-OrderFast-Event-Type: order.created
X-OrderFast-Timestamp: 1783420800
X-OrderFast-Signature: v1=4b7f...
Content-Type: application/json

Header	Descripción
X-OrderFast-Event-Id	ID único del evento — usalo para idempotencia
X-OrderFast-Event-Type	Tipo de evento (ej. sync.completed)
X-OrderFast-Timestamp	Timestamp Unix (segundos) del momento de envío
X-OrderFast-Signature	Firma HMAC del body

Cómo se calcula la firma

HMAC-SHA256(timestamp + "." + rawBody, webhook_secret)

Donde:

• timestamp es el valor de X-OrderFast-Timestamp
• rawBody es el body del request sin parsear (bytes exactos)
• webhook_secret es el secret que recibiste al crear el endpoint

El resultado se envía en X-OrderFast-Signature con el prefijo v1=.

Pasos para verificar

1. Leé el body como string crudo, antes de parsearlo como JSON.
2. Construí el string a firmar: {timestamp}.{rawBody}.
3. Calculá HMAC-SHA256 usando tu webhook_secret.
4. Compará el resultado con el valor después de v1= en X-OrderFast-Signature.
5. Si no coincide, respondé 401 y descartá el evento.

Usá comparación segura

No compares strings con ==. Usá una función de comparación en tiempo constante (ej. crypto.timingSafeEqual en Node.js) para evitar timing attacks.

Ejemplo en Node.js

import crypto from 'node:crypto';

function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-orderfast-timestamp'];
  const signature = headers['x-orderfast-signature'];

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const received = signature.replace('v1=', '');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(received),
  );
}

Validar el timestamp

Además de la firma, verificá que X-OrderFast-Timestamp no sea demasiado antiguo. Esto protege contra replay attacks.

Recomendación: rechazá eventos con más de 5 minutos de antigüedad respecto al reloj de tu servidor.

Buenas prácticas para ERP

• Guardá el secret de forma segura — nunca lo expongas en código cliente ni en logs.
• Validá antes de procesar — rechazá requests sin firma válida.
• Usá HTTPS en tu endpoint — los webhooks viajan por internet en texto plano si no usás TLS.
• Registrá el X-OrderFast-Event-Id — te ayuda a detectar duplicados y a debuggear con el historial de entregas.
• Separá la validación del procesamiento — validá la firma en el handler HTTP y encolá la lógica de conciliación en un worker.