Webhooks firmados HMAC-SHA256

OfihotelPMS emite webhooks firmados HMAC-SHA256 hacia URLs registradas por el cliente para los eventos: nueva reserva, cancelación, factura Verifactu emitida, parte SES.Hospedajes enviado, error de sincronización OTA.

Cabecera de firma

X-OfihotelPMS-Signature: t=1699999999,v1=abc123def456…. La firma se calcula como HMAC-SHA256 del texto formado por el timestamp, un punto y el cuerpo, empleando el secreto compartido.

Validación en Node.js

const crypto = require("crypto");
function verify(payload, header, secret){
  const parts = Object.fromEntries(header.split(",").map(s => s.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(parts.t + "." + payload)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Validación en Python

import hmac, hashlib
def verify(payload, header, secret):
    parts = dict(x.split("=") for x in header.split(","))
    signed = parts["t"] + "." + payload
    expected = hmac.new(secret.encode(), signed.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Reintentos

OfihotelPMS reintenta con backoff exponencial: 30 s, 1 min, 5 min, 30 min, 2 h, 12 h. Tras 24 horas sin acuse 2xx, la entrega se marca como fallida y se notifica en el Área cliente.

Idempotencia

Cada evento incluye un event_id UUID v4. El receptor debe considerar el evento como idempotente y descartar duplicados en base a este identificador. La entrega puede repetirse hasta tres veces en caso de timeout, todas con el mismo event_id.

Rotación del secreto

El secreto compartido puede rotarse desde el Área cliente. Durante 24 horas, OfihotelPMS acepta tanto el secreto antiguo como el nuevo para facilitar la transición sin interrumpir el receptor.