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:
- 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. - 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.
- 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:
| Cabecera | Valor |
|---|---|
webhook-id | Identificador de la entrega, igual al id del cuerpo. Es el mismo en todos los reintentos de una entrega. |
webhook-timestamp | Cuándo se firmó este intento, en segundos Unix enteros. Cambia en cada reintento. |
webhook-signature | v1, seguido de la firma HMAC-SHA256 en base64. Cambia en cada reintento. |
Cuerpo
| Campo | Tipo | Significado |
|---|---|---|
version | 4 | Versió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. |
id | string | Identificador de la entrega, igual a webhook-id. Úsalo para saltarte las repeticiones. |
event | "disparity.opened" | Qué ha ocurrido. |
disparityId | string | Identificador de la disparidad en StayParity. |
hotel.id | string | Identificador del hotel en StayParity. |
hotel.name | string | Nombre del hotel, tal como está configurado en el portal. |
ota | string | El canal, en minúsculas: booking, expedia o el vendedor que aparece en los resultados de búsqueda, como trip o agoda. |
stayDate | string | La noche, como YYYY-MM-DD. |
occupancy | integer | Número de huéspedes, de 1 a 10. |
currency | string | Moneda del hotel, código ISO 4217 como EUR o RON. En ella se expresan directPriceMinor, otaPriceMinor y deltaMinor. |
directPriceMinor | integer | Precio de la web del hotel, en unidades menores de currency. |
otaPriceMinor | integer | Precio del canal, en unidades menores de currency. |
deltaMinor | integer | Cuánto menos cobra el canal, en unidades menores de currency. |
directPriceEurMinor | integer | Precio de la web del hotel, en céntimos de euro. |
otaPriceEurMinor | integer | Precio del canal, en céntimos de euro. |
deltaEurMinor | integer | Cuánto menos cobra el canal, en céntimos de euro. |
deltaPct | number | La 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", opcional | Solo 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.opening | object | La 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.latest | object | La lectura más reciente de la disparidad, con la misma estructura. Igual a opening hasta que otra revisión vuelva a leerla. |
detectedAt | string | Cuá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.
| Campo | Tipo | Significado |
|---|---|---|
priceMinor | integer | Precio tal como lo indicó la fuente, en unidades menores de currency. |
currency | string | Moneda de la fuente, código ISO 4217 como EUR. |
priceEurMinor | integer | El 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", opcional | Dónde lo mostraron los resultados de búsqueda: en su lista de precios o en un espacio patrocinado. |
readAt | string | Momento de la lectura en UTC, ISO 8601. |
roomLabel | string, opcional | Nombre de la habitación tal como lo mostró la fuente. |
roomRef | string, opcional | Identificador propio de la fuente para la habitación. |
roomType.name | string, opcional | Tipo de habitación del hotel al que está asignada, con el nombre configurado en el portal. |
roomType.rank | integer, opcional | Posició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", opcional | Qué dijo la fuente que incluye el precio: solo alojamiento o también desayuno. |
mappedBoard | "room_only" o "breakfast", opcional | Qué 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ó. |
freeCancellationUntil | string, opcional | Último día de cancelación gratuita, YYYY-MM-DD. |
guests | integer, opcional | Adultos para los que vale el precio. |
taxesIncluded | boolean, opcional | Si el precio incluye impuestos. |
link | string, opcional | Adó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
{
"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 standardwebhooksimport 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 standardwebhooksimport 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 "", 204PHP
composer require standard-webhooks/standard-webhooks<?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:
- Toma la clave sin
whsec_y decodifícala desde base64. Esos bytes son la clave HMAC. - Une
webhook-id,webhook-timestampy el cuerpo original con puntos:{id}.{timestamp}.{body}. - Calcula el HMAC-SHA256 de esa cadena y codifícalo en base64.
webhook-signaturees una lista de entradasv1,<firma>separadas por espacios. Acepta la entrega si alguna entradav1coincide, comparando en tiempo constante. Hoy enviamos una sola entrada.- Rechaza un
webhook-timestampa 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:
// 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 respuesta | Qué pasa |
|---|---|
| Cualquier 2xx | Entregada. No leemos el cuerpo de la respuesta, así que basta un 200 o un 204 vacío. |
| 5xx, un timeout o un error de red | Se reintenta, hasta 5 intentos en total. |
| 3xx | Fallida, sin reintento. No seguimos redirecciones, así que danos la URL final. |
| 4xx | Fallida, 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:
// 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.
Documentación técnica
Conecta StayParity con tus sistemas: webhooks firmados, el widget de reserva directa para la web del hotel y la comprobación de precios para chatbots.
Widget de reserva directa
Añade a la web de un hotel el widget de reserva directa de StayParity con un solo código. El código, el dock, lo que ve el visitante y la CSP que necesita.