Skip to content

Webhooks

The signed JSON event StayParity posts when an OTA undercuts a hotel's direct price. Signatures, retries and testing.

StayParity posts each new rate disparity to your server as JSON: a seller in hotel search results selling the same room as the hotel, both mapped to one of the hotel's room types, for less than the hotel's website. Use it to open a ticket, message a revenue manager or feed your own dashboard.

Deliveries follow Standard Webhooks, so any Standard Webhooks library can verify them. The same contract is in the OpenAPI 3.1 description.

Set up a receiver

A receiver takes three steps:

  1. Create the signing key. In the portal, go to Settings → Webhooks and choose Create key. The key starts with whsec_ and is shown once, so copy it into your receiver's config before you close the dialog. One key signs deliveries for every hotel on the account.
  2. Add your URL. Go to Settings → Alerts with the hotel selected, choose Add under Where it goes (Set up alerts if the hotel has no rule yet) and fill in Webhook URL. Each hotel has its own URL. Leave it empty to turn webhooks off for that hotel.
  3. Answer with a 2xx. Verify the signature, store the event, and reply quickly (see Retries).

Only account admins can create the key or change a webhook URL.

The URL has to be a public https:// address on the default port, of at most 2048 characters. We refuse any other port, IP addresses, localhost, single-label hosts, names ending in .local, .internal, .lan, .localhost or .home.arpa, and URLs with a username or password in them. Put any token of your own in the path or the query string instead.

We will never send an unsigned delivery. Until the account has a key, webhooks stay silent, and the portal says so next to the URL.

What gets sent

There is one event, disparity.opened. Your code should ignore any event it doesn't know, so new events don't break it.

disparity.opened

It is sent once when a check first finds an OTA cheaper than the hotel's direct price for a stay, and all of these hold:

  • the gap clears the hotel's alert rule: Cheaper by at least an amount in the hotel's currency, and at least a percentage. Both have to be met.
  • the seller is one the hotel watches.
  • the seller sells the same room as the hotel, both mapped to one of the hotel's room types: a rate disparity. A "Cheaper in hotel search" finding, where no room is named, never sends an event.

It is not sent again while that undercut stays open, however many checks see it. An undercut that opened below the thresholds and crosses them later sends its one event then, with reason set to now_over_threshold. When the undercut closes and later opens again, that is a new undercut with a new disparityId, and a new event.

It goes out as soon as the check that found it finishes. If the undercut is fixed or dismissed before the delivery goes out, it is not sent.

Headers

Every delivery is a POST with Content-Type: application/json and these headers:

HeaderValue
webhook-idThe delivery's id, the same as id in the body. The same on every retry of one delivery.
webhook-timestampWhen this attempt was signed, in whole Unix seconds. New on every retry.
webhook-signaturev1, followed by the base64 HMAC-SHA256 signature. New on every retry.

Body

FieldTypeMeaning
version4The payload version. Fields may be added under it, so ignore any you don't know. Version 2 replaced confidence with trust and added reason. Version 3 added findingKind and evidence. Version 4 added currency, directPriceMinor, otaPriceMinor and deltaMinor, so a receiver that accepted only 3 must now accept 4.
idstringThe delivery's id, the same as webhook-id. Use it to skip repeats.
event"disparity.opened"What happened.
disparityIdstringThe undercut's id in StayParity.
hotel.idstringThe hotel's id in StayParity.
hotel.namestringThe hotel's name, as set in the portal.
otastringThe channel as a lower-case slug: booking, expedia, or the seller the search results listed, such as trip or agoda.
stayDatestringThe night, as YYYY-MM-DD.
occupancyintegerThe number of guests, 1 to 10.
currencystringThe hotel's currency, as an ISO 4217 code such as EUR or RON. directPriceMinor, otaPriceMinor and deltaMinor are in it.
directPriceMinorintegerThe hotel's direct price, in minor units of currency.
otaPriceMinorintegerThe channel's price, in minor units of currency.
deltaMinorintegerHow much less the channel charges, in minor units of currency.
directPriceEurMinorintegerThe hotel's direct price, in euro cents.
otaPriceEurMinorintegerThe channel's price, in euro cents.
deltaEurMinorintegerHow much less the channel charges, in euro cents.
deltaPctnumberThe same gap as a percentage of the direct price, rounded to two decimals.
trust"seen_twice"Always seen_twice: two organic (not sponsored) reads of hotel search results at least 30 minutes apart, on the same basis, had both the hotel's and the seller's price within 1% of the first read.
reason"now_over_threshold", optionalPresent only when the undercut was already open below the rule's thresholds and has since crossed them. Absent on a new undercut.
findingKind"rate_disparity"What kind of finding this is. Always rate_disparity today: the same room on the same terms, cheaper on the seller.
evidence.openingobjectThe undercut's first reading: the hotel's offer and the seller's, as Evidence describes them. For a seen_twice undercut, the first of the two reads.
evidence.latestobjectThe newest reading of the undercut, in the same shape. The same as opening until a later check reads it again.
detectedAtstringWhen the undercut was first seen, in UTC, as ISO 8601.

Prices are integers in minor units: directPriceMinor, otaPriceMinor and deltaMinor in the hotel's currency, the EurMinor fields in euro cents whatever that currency is, and an evidence side's priceMinor in the currency it names. So 17900 is €179.00 in EUR, and ¥17,900 in JPY, which has no minor unit. Don't divide into a float and compare; compare the integers.

Evidence

Each reading has two sides, direct (the hotel's offer) and seller (the seller's), with the same fields. A field the source didn't state is absent.

FieldTypeMeaning
priceMinorintegerThe price as the source quoted it, in minor units of currency.
currencystringThe currency the source quoted, as an ISO 4217 code such as EUR.
priceEurMinorintegerThe same price, in euro cents.
source"booking_engine" or "google"Where it was read: the hotel's booking engine (booking_engine, not live yet: every direct price today comes from google) or the list of prices in hotel search results (google: Google Hotels).
placement"organic" or "ad", optionalWhere the search results listed it: in their list of prices, or in a sponsored slot.
readAtstringWhen it was read, in UTC, as ISO 8601.
roomLabelstring, optionalThe room's name as the source showed it.
roomRefstring, optionalThe source's own id for the room.
roomType.namestring, optionalThe hotel's room type the room is mapped to, as named in the portal.
roomType.rankinteger, optionalThat room type's place among the hotel's room types, from the entry room up: a higher rank is a better room.
board"room_only" or "breakfast", optionalWhat the source said the price includes: the room only, or breakfast too.
mappedBoard"room_only" or "breakfast", optionalWhat the hotel's room mapping says the price includes: on the hotel's side, its rate plan's board when the source didn't state one; on the seller's, the board of the hotel's rate plan the seller's plan is mapped to.
cancellation"free", "no_free_cancellation" or "unknown"The cancellation terms. unknown when the source didn't say.
freeCancellationUntilstring, optionalThe last day to cancel for free, as YYYY-MM-DD.
guestsinteger, optionalThe number of adults the price is for.
taxesIncludedboolean, optionalWhether the price includes taxes.
linkstring, optionalWhere the offer leads. For google, the page the listing in hotel search results lands on, the seller's or the hotel's own site: the price was read in hotel search results, not there. For booking_engine, the page the price was read on, when the source gives one.

Example

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

Verify the signature

Check every delivery before you trust it. The signature proves the body came from StayParity with your key and wasn't changed on the way. The timestamp stops someone replaying a delivery they captured.

Use the official Standard Webhooks library for your language. It checks the signature in constant time and rejects timestamps more than five minutes from your clock. Give it the whole key, whsec_ included, and the raw body: the exact bytes that arrived, before any JSON parsing. A body parsed and serialised again won't match the signature.

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

Without a library

If you can't add a dependency, the check is short:

  1. Take the key after whsec_ and base64-decode it. Those bytes are the HMAC key.
  2. Join webhook-id, webhook-timestamp and the raw body with dots: {id}.{timestamp}.{body}.
  3. Compute the HMAC-SHA256 of that string and base64-encode it.
  4. webhook-signature is a space-separated list of v1,<signature> entries. Accept the delivery if any v1 entry matches, compared in constant time. We send one entry today.
  5. Reject a webhook-timestamp more than five minutes from your clock, in either direction.

The same steps in TypeScript, with Web Crypto only, so it runs in Node 20+, Bun, Deno and 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));
}

Retries

Answer within 10 seconds. What we do next depends on the answer:

Your answerWhat happens
Any 2xxDelivered. We don't read the response body, so an empty 200 or 204 is enough.
5xx, a timeout, or a network errorTried again, up to 5 attempts in all.
3xxFailed, not retried. Redirects are not followed, so give us the final URL.
4xxFailed, not retried. Answer 4xx only when a retry can't help.

The waits between attempts are about 10, 20, 40 and 80 seconds. Each wait varies by up to half either way, so retries don't arrive in lockstep. Every attempt is signed again with a new timestamp, and keeps the same webhook-id.

Deliveries can arrive in any order, and one delivery can arrive more than once. Sort by detectedAt, not by arrival, and handle repeats as below.

The URL and the key are read again on each attempt. If you change the URL while retries are pending, the next attempt goes to the new one.

When all 5 attempts fail, the delivery stops and Settings → Alerts shows why. Once your server is fixed, an account admin can press Retry there to send the newest failed delivery again, with the same webhook-id.

Handle repeats

Delivery is at least once. A timeout on our side can mean your server did the work and the answer was lost, and then the same delivery comes again. A delivery sent again with Retry in the portal repeats too.

webhook-id stays the same on every retry of one delivery. Keep the ids you've handled, for a few days at least, and answer 2xx without doing the work again when one comes back. Because the id is in a header, you can check it before you parse the body.

We build the body again from the live undercut on each attempt, so a repeat with the same webhook-id can carry newer prices than the first. Skip repeats by webhook-id, and if you keep the body, treat the latest one you received as current.

To act once per undercut rather than once per delivery, key on disparityId.

Rotate the key

Go to Settings → Webhooks and choose Replace key. The old key stops working immediately; there is no overlap period. The new key is shown once.

Between replacing the key and deploying it to your receiver, deliveries are signed with the new key and your receiver will reject them. If it answers 4xx, those deliveries are not retried. To keep them, put the new key in place right away, or have your receiver answer 5xx for a signature it can't verify while you switch, so the retries carry them over. The retries span about two and a half minutes, sometimes little more than one, so they only cover a quick switch. For a delivery that fails anyway, press Retry in Settings → Alerts once the new key is in place. It sends the newest failed delivery again.

Replace the key whenever it may have leaked: a commit, a log line, a shared screen.

Test your endpoint

There is no test button in the portal yet. To try your receiver, sign the example event yourself with your key and post it, exactly as we would. Save the example as event.json, then:

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

Then check the unhappy paths: change one character of the body and expect a rejection; resend the same id and expect it to be skipped.

For a local receiver, expose it through a tunnel with a public https:// name, since we only post to public addresses.

Troubleshooting

Settings → Alerts shows, under each hotel's webhook URL, when it last delivered, or why the last delivery failed:

  • No signing key: the account has no key yet. Create one under Settings → Webhooks.
  • Rejected: your server answered 3xx or 4xx, or the URL is no longer allowed.
  • Unreachable: 5 attempts timed out, answered 5xx or couldn't connect.
  • No webhook set: the URL was removed, or Alerting was turned off, after the delivery was queued.

When the cause is fixed, Retry next to the failure sends the newest failed delivery again.

When every signature fails:

  • The body was parsed before verifying. Verify the raw bytes, then parse.
  • The key is an old one. After Replace key, only the new key works.
  • The key lost its prefix or gained whitespace when pasted. Pass the whole whsec_… string to the library.
  • Your server's clock is off by more than five minutes. Sync it with NTP.

When nothing arrives:

  • The hotel's alert rule is off, or no undercut has cleared its thresholds yet.
  • The undercuts so far are from sellers the hotel doesn't watch, or are "Cheaper in hotel search" findings, which never send an event.
  • Your firewall drops requests it doesn't know. We don't publish a fixed list of addresses, so authenticate with the signature rather than the source IP.

On this page