Ir al contenido

Webhooks

El evento JSON firmado que StayParity envía cuando una OTA vende por debajo del precio de la web de un hotel. Firmas, reintentos y pruebas.

StayParity envía a tu servidor, en JSON, cada nueva disparidad de precio: un vendedor de los resultados de búsqueda de hoteles que vende la misma habitación que el hotel, ambas asignadas a uno de los tipos de habitación del hotel, por menos que la web del hotel. Úsalo para abrir una incidencia, escribir a un revenue manager o alimentar tu propio panel.

Las entregas siguen Standard Webhooks, así que cualquier biblioteca de Standard Webhooks puede verificarlas. El mismo contrato está en la descripción OpenAPI 3.1.

Configurar un receptor

Un receptor se configura en tres pasos:

  1. Crea la clave de firma. En el portal, ve a Configuración → Webhooks y elige Crear clave. La clave empieza por whsec_ y se muestra una sola vez, así que cópiala en la configuración de tu receptor antes de cerrar el diálogo. Una sola clave firma las entregas de todos los hoteles de la cuenta.
  2. Añade tu URL. Ve a Configuración → Alertas con el hotel seleccionado, pulsa Añadir en Adónde va la alerta (Configurar alertas si el hotel aún no tiene regla) y rellena URL del webhook. Cada hotel tiene su propia URL. Déjala vacía para desactivar los webhooks de ese hotel.
  3. Responde con un 2xx. Verifica la firma, guarda el evento y responde rápido (consulta Reintentos).

Solo los administradores de la cuenta pueden crear la clave o cambiar la URL de un webhook.

La URL tiene que ser una dirección https:// pública, en el puerto predeterminado y de 2048 caracteres como máximo. Rechazamos cualquier otro puerto, las direcciones IP, localhost, los hosts de una sola etiqueta, los nombres acabados en .local, .internal, .lan, .localhost o .home.arpa, y las URL con usuario o contraseña. Si necesitas un token propio, ponlo en la ruta o en la cadena de consulta.

Nunca enviaremos una entrega sin firmar. Mientras la cuenta no tenga clave, los webhooks no envían nada, y el portal lo indica junto a la URL.

Qué se envía

Hay un único evento, disparity.opened. Tu código debe ignorar cualquier event que no conozca, para que los eventos nuevos no lo rompan.

disparity.opened

Se envía una vez, cuando una revisión encuentra por primera vez una OTA más barata que el precio de la web del hotel para una estancia, y se cumple todo esto:

  • La diferencia supera la regla de alertas del hotel: Más barato al menos en un importe en la moneda del hotel y al menos en un porcentaje. Tienen que cumplirse los dos.
  • El vendedor es uno de los que sigue el hotel.
  • El vendedor vende la misma habitación que el hotel, ambas asignadas a uno de los tipos de habitación del hotel: una disparidad de precio. Un hallazgo «Más barato en la búsqueda de hoteles», que no indica ninguna habitación, nunca envía un evento.

No se vuelve a enviar mientras esa disparidad siga abierta, por muchas revisiones que la vean. Una disparidad que se abrió por debajo de los umbrales y los supera después envía entonces su único evento, con reason igual a now_over_threshold. Si la disparidad se cierra y más tarde vuelve a abrirse, es una disparidad nueva, con otro disparityId y otro evento.

Sale en cuanto termina la revisión que la encontró. Si la disparidad se corrige o se descarta antes de que salga la entrega, no se envía.

Cabeceras

Cada entrega es un POST con Content-Type: application/json y estas cabeceras:

CabeceraValor
webhook-idIdentificador de la entrega, igual al id del cuerpo. Es el mismo en todos los reintentos de una entrega.
webhook-timestampCuándo se firmó este intento, en segundos Unix enteros. Cambia en cada reintento.
webhook-signaturev1, seguido de la firma HMAC-SHA256 en base64. Cambia en cada reintento.

Cuerpo

CampoTipoSignificado
version4Versión del formato. Pueden añadirse campos sin cambiar de versión, así que ignora los que no conozcas. La versión 2 sustituyó confidence por trust y añadió reason. La versión 3 añadió findingKind y evidence. La versión 4 añadió currency, directPriceMinor, otaPriceMinor y deltaMinor, así que un receptor que solo aceptaba 3 debe aceptar ahora 4.
idstringIdentificador de la entrega, igual a webhook-id. Úsalo para saltarte las repeticiones.
event"disparity.opened"Qué ha ocurrido.
disparityIdstringIdentificador de la disparidad en StayParity.
hotel.idstringIdentificador del hotel en StayParity.
hotel.namestringNombre del hotel, tal como está configurado en el portal.
otastringEl canal, en minúsculas: booking, expedia o el vendedor que aparece en los resultados de búsqueda, como trip o agoda.
stayDatestringLa noche, como YYYY-MM-DD.
occupancyintegerNúmero de huéspedes, de 1 a 10.
currencystringMoneda del hotel, código ISO 4217 como EUR o RON. En ella se expresan directPriceMinor, otaPriceMinor y deltaMinor.
directPriceMinorintegerPrecio de la web del hotel, en unidades menores de currency.
otaPriceMinorintegerPrecio del canal, en unidades menores de currency.
deltaMinorintegerCuánto menos cobra el canal, en unidades menores de currency.
directPriceEurMinorintegerPrecio de la web del hotel, en céntimos de euro.
otaPriceEurMinorintegerPrecio del canal, en céntimos de euro.
deltaEurMinorintegerCuánto menos cobra el canal, en céntimos de euro.
deltaPctnumberLa misma diferencia como porcentaje del precio de la web, redondeada a dos decimales.
trust"seen_twice"Siempre seen_twice: dos lecturas orgánicas (no patrocinadas) de los resultados de búsqueda de hoteles con al menos 30 minutos de diferencia, sobre la misma base, con el precio del hotel y el del vendedor a menos de un 1 % de la primera lectura.
reason"now_over_threshold", opcionalSolo si la disparidad ya estaba abierta por debajo de los umbrales de la regla y los ha superado después. No aparece en una disparidad nueva.
findingKind"rate_disparity"Tipo de hallazgo. Hoy siempre rate_disparity: la misma habitación, en las mismas condiciones, más barata en el vendedor.
evidence.openingobjectLa primera lectura de la disparidad: la oferta del hotel y la del vendedor, como se describe en Evidencias. En una disparidad seen_twice, la primera de las dos.
evidence.latestobjectLa lectura más reciente de la disparidad, con la misma estructura. Igual a opening hasta que otra revisión vuelva a leerla.
detectedAtstringCuándo se vio la disparidad por primera vez, en UTC, ISO 8601.

Los importes son enteros en unidades menores: directPriceMinor, otaPriceMinor y deltaMinor, en la moneda del hotel que indica currency; los campos EurMinor, en céntimos de euro, sea cual sea esa moneda, y el priceMinor de cada lado de la evidencia, en la moneda que indica su propio currency. Así, 17900 es 179,00 € en EUR y 17.900 ¥ en JPY, que no tiene unidades menores. No los dividas para pasarlos a coma flotante y compararlos: compara los enteros.

Evidencias

Cada lectura tiene dos lados, direct (la oferta del hotel) y seller (la del vendedor), con los mismos campos. Los campos que la fuente no indicó no aparecen.

CampoTipoSignificado
priceMinorintegerPrecio tal como lo indicó la fuente, en unidades menores de currency.
currencystringMoneda de la fuente, código ISO 4217 como EUR.
priceEurMinorintegerEl mismo precio en céntimos de euro.
source"booking_engine" o "google"Dónde se leyó: el motor de reservas del hotel (booking_engine, aún no disponible: hoy todo precio de la web del hotel viene de google) o la lista de precios de los resultados de búsqueda de hoteles (google: Google Hotels).
placement"organic" o "ad", opcionalDónde lo mostraron los resultados de búsqueda: en su lista de precios o en un espacio patrocinado.
readAtstringMomento de la lectura en UTC, ISO 8601.
roomLabelstring, opcionalNombre de la habitación tal como lo mostró la fuente.
roomRefstring, opcionalIdentificador propio de la fuente para la habitación.
roomType.namestring, opcionalTipo de habitación del hotel al que está asignada, con el nombre configurado en el portal.
roomType.rankinteger, opcionalPosición de ese tipo entre los del hotel, desde la habitación básica: un valor mayor es una habitación superior.
board"room_only" o "breakfast", opcionalQué dijo la fuente que incluye el precio: solo alojamiento o también desayuno.
mappedBoard"room_only" o "breakfast", opcionalQué incluye el precio según el mapeo de habitaciones del hotel: en el lado del hotel, el régimen de su plan de tarifas cuando la fuente no indicó ninguno; en el del vendedor, el régimen del plan de tarifas del hotel al que está mapeado el del vendedor.
cancellation"free", "no_free_cancellation" o "unknown"Condiciones de cancelación. unknown si la fuente no las indicó.
freeCancellationUntilstring, opcionalÚltimo día de cancelación gratuita, YYYY-MM-DD.
guestsinteger, opcionalAdultos para los que vale el precio.
taxesIncludedboolean, opcionalSi el precio incluye impuestos.
linkstring, opcionalAdónde lleva la oferta. Para google, la página a la que lleva el resultado de la búsqueda de hoteles, la del vendedor o la web del propio hotel: el precio se leyó en los resultados de búsqueda de hoteles, no allí. Para booking_engine, la página donde se leyó el precio, cuando la fuente la da.

Ejemplo

disparity.opened
{
  "version": 4,
  "id": "mh7d0xq4c2v9n8b1k6t3r5w0z2y4p8s6",
  "event": "disparity.opened",
  "disparityId": "jn7cq2b1x9d8w4fzr3m6kt5v0h7s2e8a",
  "hotel": { "id": "kd72mbx0vy4p9s1c6tqh8wf3gr5n2j7e", "name": "Hotel Aurora" },
  "ota": "booking",
  "stayDate": "2026-10-16",
  "occupancy": 2,
  "currency": "EUR",
  "directPriceMinor": 18800,
  "otaPriceMinor": 17900,
  "deltaMinor": 900,
  "directPriceEurMinor": 18800,
  "otaPriceEurMinor": 17900,
  "deltaEurMinor": 900,
  "deltaPct": 4.79,
  "trust": "seen_twice",
  "findingKind": "rate_disparity",
  "evidence": {
    "opening": {
      "direct": {
        "priceMinor": 18800,
        "currency": "EUR",
        "priceEurMinor": 18800,
        "source": "google",
        "readAt": "2026-10-09T12:01:47.000Z",
        "roomLabel": "Double Room with Sea View",
        "mappedBoard": "breakfast",
        "cancellation": "free"
      },
      "seller": {
        "priceMinor": 17900,
        "currency": "EUR",
        "priceEurMinor": 17900,
        "source": "google",
        "readAt": "2026-10-09T12:01:47.000Z",
        "roomLabel": "Double Room - Sea View",
        "board": "breakfast",
        "cancellation": "free"
      }
    },
    "latest": {
      "direct": {
        "priceMinor": 18800,
        "currency": "EUR",
        "priceEurMinor": 18800,
        "source": "google",
        "readAt": "2026-10-09T12:41:47.000Z",
        "roomLabel": "Double Room with Sea View",
        "mappedBoard": "breakfast",
        "cancellation": "free"
      },
      "seller": {
        "priceMinor": 17900,
        "currency": "EUR",
        "priceEurMinor": 17900,
        "source": "google",
        "readAt": "2026-10-09T12:41:47.000Z",
        "roomLabel": "Double Room - Sea View",
        "board": "breakfast",
        "cancellation": "free"
      }
    }
  },
  "detectedAt": "2026-10-09T12:02:00.000Z"
}

Verificar la firma

Verifica cada entrega antes de fiarte de ella. La firma demuestra que el cuerpo viene de StayParity con tu clave y que nadie lo ha cambiado por el camino. La marca de tiempo impide que alguien repita una entrega que haya capturado.

Usa la biblioteca oficial de Standard Webhooks para tu lenguaje. Compara la firma en tiempo constante y rechaza las marcas de tiempo a más de cinco minutos de tu reloj. Pásale la clave completa, con whsec_ incluido, y el cuerpo original: los bytes exactos que llegaron, antes de analizar el JSON. Un cuerpo analizado y vuelto a serializar no coincidirá con la firma.

Node

npm install express standardwebhooks
server.js
import express from "express";
import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.STAYPARITY_WEBHOOK_SECRET);
const app = express();

// express.raw keeps the body as bytes, as it arrived.
app.post("/stayparity", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = webhook.verify(req.body.toString("utf8"), req.headers);
  } catch {
    return res.status(401).end();
  }
  // Store it and answer now; do the slow work afterwards.
  res.status(204).end();
});

Python

pip install flask standardwebhooks
app.py
import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

app = Flask(__name__)
webhook = Webhook(os.environ["STAYPARITY_WEBHOOK_SECRET"])

@app.post("/stayparity")
def stayparity():
    try:
        event = webhook.verify(request.get_data(as_text=True), dict(request.headers))
    except WebhookVerificationError:
        return "", 401
    # Store it and answer now; do the slow work afterwards.
    return "", 204

PHP

composer require standard-webhooks/standard-webhooks
stayparity.php
<?php
require __DIR__ . '/vendor/autoload.php';

$webhook = new \StandardWebhooks\Webhook(getenv('STAYPARITY_WEBHOOK_SECRET'));
$body = file_get_contents('php://input');
$headers = array_change_key_case(getallheaders(), CASE_LOWER);

try {
    $event = $webhook->verify($body, $headers);
} catch (\Throwable $e) {
    http_response_code(401);
    exit;
}
// Store it and answer now; do the slow work afterwards.
http_response_code(204);

Sin biblioteca

Si no puedes añadir una dependencia, la comprobación es corta:

  1. Toma la clave sin whsec_ y decodifícala desde base64. Esos bytes son la clave HMAC.
  2. Une webhook-id, webhook-timestamp y el cuerpo original con puntos: {id}.{timestamp}.{body}.
  3. Calcula el HMAC-SHA256 de esa cadena y codifícalo en base64.
  4. webhook-signature es una lista de entradas v1,<firma> separadas por espacios. Acepta la entrega si alguna entrada v1 coincide, comparando en tiempo constante. Hoy enviamos una sola entrada.
  5. Rechaza un webhook-timestamp a más de cinco minutos de tu reloj, en cualquier dirección.

Los mismos pasos en TypeScript, solo con Web Crypto, así que funciona en Node 20+, Bun, Deno y Cloudflare Workers:

verify-webhook.ts
// Verifies a StayParity delivery without a library. Web Crypto only, so it
// runs as is in Node 20+, Bun, Deno and Cloudflare Workers.

/** How old (or how far ahead) a delivery may be: five minutes. */
const TOLERANCE_SECONDS = 5 * 60;

/**
 * Returns the parsed event, or throws. `secret` is the whole key, `whsec_`
 * included; `rawBody` is the request body exactly as it arrived.
 */
export async function verifyWebhook(
  secret: string,
  headers: Headers,
  rawBody: string,
): Promise<unknown> {
  const id = headers.get("webhook-id");
  const timestamp = headers.get("webhook-timestamp");
  const signatures = headers.get("webhook-signature");
  if (id === null || timestamp === null || signatures === null) {
    throw new Error("Missing webhook headers");
  }

  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!(age <= TOLERANCE_SECONDS)) {
    throw new Error("Timestamp outside the tolerance");
  }

  const key = await crypto.subtle.importKey(
    "raw",
    base64ToBytes(secret.replace(/^whsec_/, "")),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["verify"],
  );
  const signed = new TextEncoder().encode(`${id}.${timestamp}.${rawBody}`);

  // A space-separated list of `v1,<base64>`. Any one valid entry will do.
  for (const entry of signatures.split(" ")) {
    const [version, signature] = entry.split(",");
    if (version !== "v1" || signature === undefined) continue;
    let bytes: Uint8Array<ArrayBuffer>;
    try {
      bytes = base64ToBytes(signature);
    } catch {
      // A malformed entry does not invalidate another, valid signature.
      continue;
    }
    const valid = await crypto.subtle.verify("HMAC", key, bytes, signed);
    if (valid) return JSON.parse(rawBody);
  }
  throw new Error("No valid signature");
}

function base64ToBytes(base64: string): Uint8Array<ArrayBuffer> {
  return Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
}

Reintentos

Responde en diez segundos como máximo. Lo que hacemos después depende de tu respuesta:

Tu respuestaQué pasa
Cualquier 2xxEntregada. No leemos el cuerpo de la respuesta, así que basta un 200 o un 204 vacío.
5xx, un timeout o un error de redSe reintenta, hasta 5 intentos en total.
3xxFallida, sin reintento. No seguimos redirecciones, así que danos la URL final.
4xxFallida, sin reintento. Responde 4xx solo cuando un reintento no pueda ayudar.

Las esperas entre intentos son de unos 10, 20, 40 y 80 segundos. Cada espera varía hasta la mitad en cada sentido, para que los reintentos no lleguen todos a la vez. Cada intento se firma de nuevo con otra marca de tiempo y conserva el mismo webhook-id.

Las entregas pueden llegar en cualquier orden, y una misma entrega puede llegar más de una vez. Ordena por detectedAt, no por orden de llegada, y trata las repeticiones como se explica abajo.

Volvemos a leer la URL y la clave en cada intento. Si cambias la URL con reintentos pendientes, el siguiente intento va a la nueva.

Cuando fallan los 5 intentos, la entrega se detiene y Configuración → Alertas muestra el motivo. Cuando hayas arreglado tu servidor, un administrador de la cuenta puede pulsar ahí Reintentar para volver a enviar la última entrega fallida, con el mismo webhook-id.

Evitar duplicados

La entrega es al menos una vez. Un timeout por nuestra parte puede significar que tu servidor hizo el trabajo y la respuesta se perdió, y entonces la misma entrega vuelve a llegar. Una entrega reenviada con Reintentar en el portal también se repite.

webhook-id es el mismo en todos los reintentos de una entrega. Guarda los identificadores que ya has procesado, al menos durante unos días, y responde 2xx sin repetir el trabajo cuando uno vuelva. Como el identificador va en una cabecera, puedes comprobarlo antes de analizar el cuerpo.

En cada intento volvemos a generar el cuerpo a partir de la disparidad tal como está, así que una repetición con el mismo webhook-id puede traer precios más recientes que la primera. Sáltate las repeticiones por webhook-id y, si guardas el cuerpo, toma como vigente el último que hayas recibido.

Para actuar una vez por disparidad y no una vez por entrega, usa disparityId como clave.

Sustituir la clave

Ve a Configuración → Webhooks y elige Sustituir clave. La clave anterior deja de funcionar al instante; no hay periodo de solapamiento. La nueva se muestra una sola vez.

Entre que sustituyes la clave y la pones en tu receptor, las entregas llegan firmadas con la clave nueva y tu receptor las rechazará. Si responde 4xx, esas entregas no se reintentan. Para conservarlas, pon la clave nueva enseguida, o haz que tu receptor responda 5xx a una firma que no puede verificar mientras haces el cambio, para que los reintentos las lleven. Los reintentos duran unos dos minutos y medio, a veces poco más de uno, así que solo cubren un cambio rápido. Si una entrega falla de todos modos, pulsa Reintentar en Configuración → Alertas cuando la clave nueva ya esté puesta: vuelve a enviar la última entrega fallida.

Sustituye la clave siempre que haya podido filtrarse: en un commit, en una línea de log, en una pantalla compartida.

Probar el endpoint

Todavía no hay botón de prueba en el portal. Para probar tu receptor, firma tú mismo el evento de ejemplo con tu clave y envíalo, igual que lo haríamos nosotros. Guarda el ejemplo como event.json y después:

send-test.mjs
// node send-test.mjs https://your-server.example/stayparity
import { readFileSync } from "node:fs";
import { Webhook } from "standardwebhooks";

const id = `test_${Date.now()}`;
const event = { ...JSON.parse(readFileSync("event.json", "utf8")), id };
const body = JSON.stringify(event);
const now = new Date();

const response = await fetch(process.argv[2], {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "webhook-id": id,
    "webhook-timestamp": String(Math.floor(now.getTime() / 1000)),
    "webhook-signature": new Webhook(process.env.STAYPARITY_WEBHOOK_SECRET).sign(id, now, body),
  },
  body,
});
console.log(response.status);

Después, prueba los casos de error: cambia un carácter del cuerpo y espera un rechazo; reenvía el mismo identificador y espera que se lo salte.

Para un receptor local, publícalo con un túnel que tenga un nombre https:// público, porque solo enviamos a direcciones públicas.

Diagnóstico

Configuración → Alertas muestra, bajo la URL del webhook de cada hotel, cuándo fue la última entrega o por qué falló:

  • Sin clave de firma: la cuenta aún no tiene clave. Crea una en Configuración → Webhooks.
  • Rechazada: tu servidor respondió 3xx o 4xx, o la URL ya no está permitida.
  • Inaccesible: los 5 intentos agotaron el tiempo, recibieron un 5xx o no pudieron conectar.
  • Sin webhook configurado: se eliminó la URL, o se desactivó Envío de alertas, después de poner la entrega en cola.

Cuando hayas resuelto la causa, Reintentar, junto al fallo, vuelve a enviar la última entrega fallida.

Si fallan todas las firmas:

  • El cuerpo se analizó antes de verificarlo. Verifica los bytes originales y analiza después.
  • La clave es una antigua. Después de Sustituir clave, solo funciona la nueva.
  • La clave perdió el prefijo o ganó espacios al pegarla. Pasa a la biblioteca la cadena whsec_… completa.
  • El reloj de tu servidor va desfasado más de cinco minutos. Sincronízalo con NTP.

Si no llega nada:

  • La regla de alertas del hotel está desactivada, o ninguna disparidad ha superado aún sus umbrales.
  • Las disparidades encontradas hasta ahora son de vendedores que el hotel no sigue, o son hallazgos «Más barato en la búsqueda de hoteles», que nunca envían un evento.
  • Tu cortafuegos descarta las solicitudes que no conoce. No publicamos una lista fija de direcciones, así que autentica con la firma y no con la IP de origen.

En esta página