Vai al contenuto

Webhook

L’evento JSON firmato che StayParity invia quando un’OTA vende a meno della tariffa diretta di un hotel. Firme, nuovi tentativi e test.

StayParity invia al tuo server ogni nuova discrepanza tariffaria come JSON: un portale nei risultati di ricerca degli hotel che vende la stessa camera dell’hotel, entrambe abbinate a una delle tipologie di camera dell’hotel, a meno del sito dell’hotel. Usalo per aprire un ticket, avvisare il revenue manager o alimentare la tua dashboard.

Gli invii seguono Standard Webhooks, quindi qualsiasi libreria Standard Webhooks li può verificare. Lo stesso contratto è nella descrizione OpenAPI 3.1.

Configura un ricevitore

Per configurare un ricevitore servono tre passaggi:

  1. Crea la chiave di firma. Nell’applicazione, vai su Impostazioni → Webhook e scegli Crea chiave. La chiave inizia con whsec_ e viene mostrata una sola volta: copiala nella configurazione del ricevitore prima di chiudere la finestra. Una sola chiave firma gli invii di tutti gli hotel dell’account.
  2. Aggiungi il tuo URL. Vai su Impostazioni → Notifiche con l’hotel selezionato, scegli Aggiungi sotto Dove arriva la notifica (Configura le notifiche se l’hotel non ha ancora una regola) e compila URL del webhook. Ogni hotel ha il suo URL. Lascialo vuoto per disattivare i webhook di quell’hotel.
  3. Rispondi con un 2xx. Verifica la firma, salva l’evento e rispondi subito (vedi Nuovi tentativi).

Solo gli amministratori dell’account possono creare la chiave o modificare l’URL di un webhook.

L’URL deve essere un indirizzo https:// pubblico sulla porta predefinita, di massimo 2048 caratteri. Rifiutiamo qualsiasi altra porta, gli indirizzi IP, localhost, gli host con una sola etichetta, i nomi che terminano in .local, .internal, .lan, .localhost o .home.arpa e gli URL che contengono nome utente o password. Metti un tuo eventuale token nel percorso o nella query string.

Non inviamo mai un evento senza firma. Finché l’account non ha una chiave, i webhook restano inattivi e l’applicazione lo indica accanto all’URL.

Eventi inviati

C’è un solo evento, disparity.opened. Il tuo codice deve ignorare qualsiasi event che non conosce, così i nuovi eventi non lo bloccano.

disparity.opened

Viene inviato una volta, quando un controllo trova per la prima volta un’OTA più economica della tariffa diretta dell’hotel per un soggiorno e valgono tutte queste condizioni:

  • la differenza supera la regola di notifica dell’hotel: Sotto di almeno un importo nella valuta dell’hotel e di almeno una percentuale. Servono entrambe.
  • il portale è uno di quelli che l’hotel monitora.
  • il portale vende la stessa camera dell’hotel, entrambe abbinate a una delle tipologie di camera dell’hotel: una discrepanza tariffaria. Una discrepanza «Più basso nella ricerca hotel», in cui non è indicata nessuna camera, non invia mai un evento.

Finché la discrepanza resta aperta, l’evento non viene inviato di nuovo, per quanti controlli la vedano. Una discrepanza aperta sotto le soglie che le supera in seguito invia in quel momento il suo unico evento, con reason impostato a now_over_threshold. Se la discrepanza si chiude e poi si riapre, è una nuova discrepanza, con un nuovo disparityId e un nuovo evento.

L’evento parte appena finisce il controllo che ha trovato la discrepanza. Se la discrepanza viene corretta o scartata prima dell’invio, l’evento non parte.

Intestazioni

Ogni invio è un POST con Content-Type: application/json e queste intestazioni:

IntestazioneValore
webhook-idL’identificatore dell’invio, uguale a id nel corpo. Resta lo stesso a ogni nuovo tentativo dello stesso invio.
webhook-timestampQuando è stato firmato questo tentativo, in secondi Unix interi. Cambia a ogni nuovo tentativo.
webhook-signaturev1, seguito dalla firma HMAC-SHA256 in base64. Cambia a ogni nuovo tentativo.

Corpo

CampoTipoSignificato
version4La versione del formato. Possono aggiungersi campi con la stessa versione, quindi ignora quelli che non conosci. La versione 2 ha sostituito confidence con trust e aggiunto reason. La versione 3 ha aggiunto findingKind ed evidence. La versione 4 ha aggiunto currency, directPriceMinor, otaPriceMinor e deltaMinor, quindi un ricevitore che accettava solo 3 deve ora accettare 4.
idstringL’identificatore dell’invio, uguale a webhook-id. Usalo per saltare i duplicati.
event"disparity.opened"Che cosa è successo.
disparityIdstringL’identificatore della discrepanza in StayParity.
hotel.idstringL’identificatore dell’hotel in StayParity.
hotel.namestringIl nome dell’hotel, come impostato nell’applicazione.
otastringIl canale come slug in minuscolo: booking, expedia o il portale elencato nei risultati di ricerca, come trip o agoda.
stayDatestringLa notte, nel formato YYYY-MM-DD.
occupancyintegerIl numero di ospiti, da 1 a 10.
currencystringLa valuta dell’hotel, in codice ISO 4217, ad esempio EUR o RON. directPriceMinor, otaPriceMinor e deltaMinor sono espressi in questa valuta.
directPriceMinorintegerLa tariffa diretta dell’hotel, in unità minori di currency.
otaPriceMinorintegerIl prezzo del canale, in unità minori di currency.
deltaMinorintegerQuanto meno chiede il canale, in unità minori di currency.
directPriceEurMinorintegerLa tariffa diretta dell’hotel, in centesimi di euro.
otaPriceEurMinorintegerIl prezzo del canale, in centesimi di euro.
deltaEurMinorintegerQuanto meno chiede il canale, in centesimi di euro.
deltaPctnumberLa stessa differenza in percentuale della tariffa diretta, arrotondata a due decimali.
trust"seen_twice"Sempre seen_twice: due rilevazioni organiche (non sponsorizzate) dei risultati di ricerca degli hotel, ad almeno 30 minuti di distanza e sulla stessa base, hanno trovato sia il prezzo dell’hotel sia quello del portale entro l’1% della prima rilevazione.
reason"now_over_threshold", facoltativoPresente solo se la discrepanza era già aperta sotto le soglie della regola e le ha superate in seguito. Assente su una discrepanza nuova.
findingKind"rate_disparity"Il tipo di discrepanza. Oggi sempre rate_disparity: la stessa camera alle stesse condizioni, più economica sul portale.
evidence.openingobjectLa prima rilevazione della discrepanza: l’offerta dell’hotel e quella del portale, come le descrive Evidenze. Per una discrepanza seen_twice, la prima delle due rilevazioni.
evidence.latestobjectLa rilevazione più recente della discrepanza, con la stessa struttura. Uguale a opening finché un controllo successivo non la rileva di nuovo.
detectedAtstringQuando la discrepanza è stata vista per la prima volta, in UTC, in formato ISO 8601.

Gli importi sono interi in unità minori: directPriceMinor, otaPriceMinor e deltaMinor nella valuta dell’hotel indicata da currency, i campi EurMinor in centesimi di euro qualunque sia quella valuta, e il priceMinor di ogni lato delle evidenze nella valuta indicata dal suo currency. Quindi 17900 è 179,00 € in EUR e 17.900 ¥ in JPY, che non ha unità minori. Non dividere per ottenere un numero in virgola mobile da confrontare: confronta gli interi.

Evidenze

Ogni rilevazione ha due lati, direct (l’offerta dell’hotel) e seller (quella del portale), con gli stessi campi. Un campo che la fonte non ha indicato è assente.

CampoTipoSignificato
priceMinorintegerIl prezzo come indicato dalla fonte, in unità minori di currency.
currencystringLa valuta indicata dalla fonte, in codice ISO 4217, ad esempio EUR.
priceEurMinorintegerLo stesso prezzo, in centesimi di euro.
source"booking_engine" o "google"Dove è stato rilevato: il booking engine dell’hotel (booking_engine, non ancora attivo: oggi ogni tariffa diretta arriva da google) o l’elenco dei prezzi nei risultati di ricerca degli hotel (google: Google Hotels).
placement"organic" o "ad", facoltativoDove l’hanno mostrato i risultati di ricerca: nel loro elenco dei prezzi o in uno spazio sponsorizzato.
readAtstringQuando è stato rilevato, in UTC, in formato ISO 8601.
roomLabelstring, facoltativoIl nome della camera come lo mostrava la fonte.
roomRefstring, facoltativoL’identificatore della camera presso la fonte.
roomType.namestring, facoltativoLa tipologia di camera dell’hotel a cui la camera è abbinata, con il nome impostato nell’applicazione.
roomType.rankinteger, facoltativoLa posizione di quella tipologia tra quelle dell’hotel, dalla camera base in su: un valore più alto indica una camera migliore.
board"room_only" o "breakfast", facoltativoChe cosa include il prezzo secondo la fonte: solo pernottamento o anche la colazione.
mappedBoard"room_only" o "breakfast", facoltativoChe cosa include il prezzo secondo l’abbinamento delle camere dell’hotel: dal lato dell’hotel, il trattamento del suo piano tariffario quando la fonte non ne ha indicato uno; dal lato del portale, il trattamento del piano tariffario dell’hotel a cui è abbinato il piano del portale.
cancellation"free", "no_free_cancellation" o "unknown"Le condizioni di cancellazione. unknown se la fonte non le ha indicate.
freeCancellationUntilstring, facoltativoL’ultimo giorno per cancellare gratis, nel formato YYYY-MM-DD.
guestsinteger, facoltativoIl numero di adulti a cui si riferisce il prezzo.
taxesIncludedboolean, facoltativoSe il prezzo include le tasse.
linkstring, facoltativoDove porta l’offerta. Per google, la pagina a cui porta la voce nei risultati di ricerca degli hotel, quella del portale o il sito dell’hotel: il prezzo è stato rilevato nei risultati di ricerca degli hotel, non lì. Per booking_engine, la pagina su cui è stato rilevato il prezzo, quando la fonte la indica.

Esempio

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"
}

Verifica la firma

Controlla ogni invio prima di fidarti. La firma prova che il corpo arriva da StayParity con la tua chiave e non è stato modificato lungo il percorso. Il timestamp impedisce a qualcuno di ripetere un invio che ha intercettato.

Usa la libreria ufficiale Standard Webhooks per il tuo linguaggio. Controlla la firma a tempo costante e rifiuta i timestamp distanti più di cinque minuti dal tuo orologio. Passale la chiave intera, whsec_ compreso, e il corpo originale: i byte esatti che sono arrivati, prima di qualsiasi analisi del JSON. Un corpo analizzato e poi serializzato di nuovo non corrisponde alla 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);

Senza libreria

Se non puoi aggiungere una dipendenza, il controllo è breve:

  1. Prendi la chiave dopo whsec_ e decodificala da base64. Quei byte sono la chiave HMAC.
  2. Unisci con dei punti webhook-id, webhook-timestamp e il corpo originale: {id}.{timestamp}.{body}.
  3. Calcola l’HMAC-SHA256 di questa stringa e codificalo in base64.
  4. webhook-signature è un elenco di voci v1,<firma> separate da spazi. Accetta l’invio se una qualsiasi voce v1 coincide, con un confronto a tempo costante. Oggi inviamo una sola voce.
  5. Rifiuta un webhook-timestamp distante più di cinque minuti dal tuo orologio, in entrambe le direzioni.

Gli stessi passaggi in TypeScript, solo con Web Crypto, quindi funziona in Node 20+, Bun, Deno e 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));
}

Nuovi tentativi

Rispondi entro 10 secondi. Che cosa succede dopo dipende dalla risposta:

La tua rispostaChe cosa succede
Qualsiasi 2xxConsegnato. Non leggiamo il corpo della risposta, quindi basta un 200 o un 204 vuoto.
5xx, timeout o errore di reteNuovo tentativo, fino a 5 tentativi in tutto.
3xxFallito, senza nuovi tentativi. Non seguiamo i reindirizzamenti, quindi indicaci l’URL finale.
4xxFallito, senza nuovi tentativi. Rispondi 4xx solo quando un nuovo tentativo non può servire.

Tra un tentativo e l’altro passano circa 10, 20, 40 e 80 secondi. Ogni attesa varia fino alla metà in più o in meno, così i nuovi tentativi non arrivano tutti insieme. Ogni tentativo viene firmato di nuovo con un nuovo timestamp e mantiene lo stesso webhook-id.

Gli invii possono arrivare in qualsiasi ordine e lo stesso invio può arrivare più di una volta. Ordina per detectedAt, non per ordine di arrivo, e gestisci i duplicati come spiegato sotto.

L’URL e la chiave vengono letti di nuovo a ogni tentativo. Se cambi l’URL mentre ci sono tentativi in attesa, il tentativo successivo va al nuovo URL.

Quando falliscono tutti e 5 i tentativi, l’invio si ferma e Impostazioni → Notifiche ne indica il motivo. Una volta sistemato il server, un amministratore dell’account può premere Riprova per inviare di nuovo l’ultimo invio fallito, con lo stesso webhook-id.

Gestisci gli invii ripetuti

La consegna avviene almeno una volta. Un timeout dal nostro lato può significare che il tuo server ha svolto il lavoro e la risposta è andata persa: allora lo stesso invio arriva di nuovo. Anche un invio ripetuto con Riprova nell’applicazione arriva di nuovo.

webhook-id resta lo stesso a ogni nuovo tentativo dello stesso invio. Conserva gli id che hai già gestito, almeno per qualche giorno, e quando uno torna rispondi 2xx senza ripetere il lavoro. Dato che l’id è in un’intestazione, puoi controllarlo prima di analizzare il corpo.

A ogni tentativo ricostruiamo il corpo dalla discrepanza attuale, quindi un duplicato con lo stesso webhook-id può contenere prezzi più recenti del primo. Salta i duplicati in base a webhook-id e, se conservi il corpo, considera attuale l’ultimo che hai ricevuto.

Per agire una volta per discrepanza e non una volta per invio, usa disparityId come chiave.

Sostituisci la chiave

Vai su Impostazioni → Webhook e scegli Sostituisci chiave. La vecchia chiave smette subito di funzionare: non c’è un periodo di sovrapposizione. La nuova chiave viene mostrata una sola volta.

Tra la sostituzione della chiave e il suo inserimento nel ricevitore, gli invii sono firmati con la nuova chiave e il ricevitore li rifiuta. Se risponde 4xx, quegli invii non vengono ritentati. Per non perderli, inserisci subito la nuova chiave, oppure fai rispondere al ricevitore 5xx a una firma che non riesce a verificare mentre fai il cambio, così i nuovi tentativi li recuperano. I nuovi tentativi coprono circa due minuti e mezzo, a volte poco più di uno, quindi bastano solo per un cambio rapido. Per un invio che fallisce comunque, premi Riprova in Impostazioni → Notifiche quando la nuova chiave è attiva: invia di nuovo l’ultimo invio fallito.

Sostituisci la chiave ogni volta che potrebbe essere stata esposta: un commit, una riga di log, uno schermo condiviso.

Testa il tuo endpoint

Nell’applicazione non c’è ancora un pulsante di test. Per provare il ricevitore, firma tu l’evento di esempio con la tua chiave e invialo, esattamente come faremmo noi. Salva l’esempio come event.json, poi:

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);

Poi controlla i casi di errore: cambia un carattere del corpo e aspettati un rifiuto; invia di nuovo lo stesso id e aspettati che venga saltato.

Per un ricevitore locale, esponilo tramite un tunnel con un nome https:// pubblico, perché inviamo solo a indirizzi pubblici.

Risoluzione dei problemi

Impostazioni → Notifiche mostra, sotto l’URL del webhook di ogni hotel, quando ha consegnato l’ultima volta o perché l’ultimo invio è fallito:

  • Nessuna chiave di firma: l’account non ha ancora una chiave. Creane una in Impostazioni → Webhook.
  • Rifiutata: il tuo server ha risposto 3xx o 4xx, oppure l’URL non è più consentito.
  • Non raggiungibile: i 5 tentativi sono scaduti, hanno ricevuto un 5xx o non sono riusciti a connettersi.
  • Nessun webhook impostato: l’URL è stato rimosso, o Invio notifiche è stato disattivato, dopo che l’invio era stato messo in coda.

Una volta risolta la causa, Riprova accanto all’errore invia di nuovo l’ultimo invio fallito.

Quando ogni firma fallisce:

  • Il corpo è stato analizzato prima della verifica. Verifica i byte originali, poi analizza il JSON.
  • La chiave è vecchia. Dopo Sostituisci chiave funziona solo la nuova.
  • Incollando la chiave hai perso il prefisso o aggiunto spazi. Passa alla libreria l’intera stringa whsec_….
  • L’orologio del server è sfasato di più di cinque minuti. Sincronizzalo con NTP.

Quando non arriva niente:

  • La regola di notifica dell’hotel è disattivata, oppure nessuna discrepanza ha ancora superato le sue soglie.
  • Le discrepanze finora riguardano portali che l’hotel non monitora, oppure sono discrepanze «Più basso nella ricerca hotel», che non inviano mai un evento.
  • Il firewall scarta le richieste che non conosce. Non pubblichiamo un elenco fisso di indirizzi, quindi autentica con la firma e non con l’IP di origine.

In questa pagina