Guía técnica

Avisos a tu sistema (webhooks) y cómo verificarlos

Eventos de reserva firmados con HMAC-SHA256, con llave de idempotencia y reintentos con tope.

Qué se avisa

reserva.creada, reserva.estado, reserva.cancelada (con el origen: cliente, panel o api:<clave>) y reserva.reprogramada. Los afiliados tienen además sus propios avisos de conversión, firmados con su secreto.

La URL de destino se configura por acuerdo: el aviso de alta lleva datos del pasajero, así que el destino tiene que ser tu sistema o el de un encargado del tratamiento con contrato.

Cabeceras

X-VTC-Event

X-VTC-Timestamp

X-VTC-Signature

X-VTC-Idempotency-Key

X-VTC-Attempt

Verifica la firma

La firma es sha256= seguido del HMAC-SHA256 en hexadecimal de <X-VTC-Timestamp>.<cuerpo> con el secreto compartido. Rechaza marcas de tiempo de más de cinco minutos y compara en tiempo constante.

javascript

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

export function avisoValido(cuerpo, cabeceras, secreto) {
  const marca = cabeceras["x-vtc-timestamp"];
  if (Math.abs(Date.now() - Date.parse(marca)) > 5 * 60_000) return false;
  const esperada = "sha256=" + createHmac("sha256", secreto).update(`${marca}.${cuerpo}`, "utf8").digest("hex");
  const recibida = cabeceras["x-vtc-signature"] ?? "";
  return recibida.length === esperada.length && timingSafeEqual(Buffer.from(recibida), Buffer.from(esperada));
}

Reintentos e idempotencia

Cuatro intentos (el inmediato y tres reintentos a 1, 3 y 9 minutos) dentro de una ventana de 6 horas. La marca de tiempo y la firma se recalculan en cada intento; la llave de idempotencia se repite igual.

Un 404, 410 o 401 de tu lado no se reintenta: se arregla cambiando la URL o la clave. Un 429, 408 o 5xx sí.