Μετάβαση στο περιεχόμενο

Webhooks

Το υπογεγραμμένο συμβάν JSON που στέλνει το StayParity όταν ένα OTA πουλάει κάτω από την απευθείας τιμή ενός ξενοδοχείου. Υπογραφές, επαναλήψεις, δοκιμές.

Το StayParity στέλνει κάθε νέα απόκλιση τιμής στον διακομιστή σας ως JSON: ένα κανάλι στα αποτελέσματα αναζήτησης ξενοδοχείων πουλάει το ίδιο δωμάτιο με το ξενοδοχείο, με αντιστοίχιση και των δύο σε έναν από τους τύπους δωματίων του ξενοδοχείου, φθηνότερα από την ιστοσελίδα του ξενοδοχείου. Χρησιμοποιήστε το για να ανοίξετε ένα αίτημα υποστήριξης, να στείλετε μήνυμα στον υπεύθυνο εσόδων ή να τροφοδοτήσετε τον δικό σας πίνακα ελέγχου.

Οι παραδόσεις ακολουθούν το Standard Webhooks και επαληθεύονται με τις αντίστοιχες βιβλιοθήκες. Η δομή περιγράφεται και στην προδιαγραφή OpenAPI 3.1.

Ρύθμιση του endpoint

Η ρύθμιση γίνεται σε τρία βήματα:

  1. Δημιουργήστε κλειδί υπογραφής. Στην εφαρμογή, ανοίξτε τις Ρυθμίσεις → Webhook και επιλέξτε Δημιουργία κλειδιού. Το κλειδί έχει πρόθεμα whsec_ και εμφανίζεται μόνο μία φορά. Αποθηκεύστε το στις ρυθμίσεις του διακομιστή πριν κλείσετε το παράθυρο. Το ίδιο κλειδί υπογράφει τις παραδόσεις όλων των ξενοδοχείων του λογαριασμού.
  2. Ορίστε τη διεύθυνση αποστολής. Στις Ρυθμίσεις → Ειδοποιήσεις, με επιλεγμένο το ξενοδοχείο, επιλέξτε Προσθήκη στην ενότητα Πού στέλνεται η ειδοποίηση (ή Ρύθμιση ειδοποιήσεων, αν το ξενοδοχείο δεν έχει ακόμη κανόνα) και συμπληρώστε το URL του webhook. Κάθε ξενοδοχείο μπορεί να έχει διαφορετική διεύθυνση. Κενό πεδίο απενεργοποιεί τα webhooks για το συγκεκριμένο ξενοδοχείο.
  3. Επιστρέψτε απόκριση 2xx. Επαληθεύστε την υπογραφή, αποθηκεύστε το συμβάν και απαντήστε χωρίς καθυστέρηση. Δείτε τις επαναλήψεις παράδοσης.

Μόνο διαχειριστές του λογαριασμού μπορούν να δημιουργήσουν κλειδί ή να αλλάξουν διεύθυνση webhook.

Απαιτείται δημόσια διεύθυνση https:// στην προεπιλεγμένη θύρα, με μέγιστο μήκος 2048 χαρακτήρες. Δεν επιτρέπονται άλλες θύρες, διευθύνσεις IP, localhost, ονόματα host με ένα μόνο τμήμα, καταλήξεις .local, .internal, .lan, .localhost ή .home.arpa, ούτε διευθύνσεις με ενσωματωμένο όνομα χρήστη ή κωδικό. Αν χρησιμοποιείτε πρόσθετο token, προσθέστε το στη διαδρομή ή στις παραμέτρους της διεύθυνσης.

Δεν στέλνουμε ποτέ παράδοση χωρίς υπογραφή. Μέχρι ο λογαριασμός να αποκτήσει κλειδί, τα webhook δεν στέλνουν τίποτα, και η εφαρμογή το αναφέρει δίπλα στη διεύθυνση.

Υποστηριζόμενα συμβάντα

Υπάρχει ένα μόνο συμβάν, το disparity.opened. Η υλοποίησή σας πρέπει να αγνοεί άγνωστες τιμές του event, ώστε να παραμένει συμβατή με μελλοντικές προσθήκες.

disparity.opened

Στέλνεται μία φορά, όταν ένας έλεγχος βρει για πρώτη φορά ένα OTA φθηνότερο από την απευθείας τιμή του ξενοδοχείου για μια διαμονή, και ισχύουν όλα τα παρακάτω:

  • Ελάχιστη διαφορά: στον κανόνα ειδοποίησης του ξενοδοχείου, τα πεδία Φθηνότερα κατά τουλάχιστον και και τουλάχιστον ορίζουν ποσό στο νόμισμα του ξενοδοχείου και ποσοστό. Η διαφορά πρέπει να φτάνει και τα δύο όρια.
  • Κανάλι: είναι ένα από τα κανάλια που παρακολουθεί το ξενοδοχείο.
  • Δωμάτιο: το κανάλι πουλάει το ίδιο δωμάτιο με το ξενοδοχείο, με αντιστοίχιση και των δύο σε έναν από τους τύπους δωματίων του ξενοδοχείου: είναι απόκλιση τιμής. Ένα εύρημα «Φθηνότερα στην αναζήτηση», όπου δεν αναφέρεται δωμάτιο, δεν δημιουργεί ποτέ συμβάν.

Δεν στέλνεται ξανά όσο η ίδια απόκλιση παραμένει ανοιχτή, όσοι έλεγχοι κι αν τη δουν. Μια απόκλιση που άνοιξε κάτω από τα όρια και τα ξεπερνά αργότερα στέλνει τότε το μοναδικό της συμβάν, με reason ίσο με now_over_threshold. Αν κλείσει και εμφανιστεί ξανά αργότερα, δημιουργείται νέα απόκλιση, με νέο disparityId και νέο συμβάν.

Στέλνεται μόλις ολοκληρωθεί ο έλεγχος που τη βρήκε. Αν η απόκλιση διορθωθεί ή απορριφθεί πριν φύγει η παράδοση, δεν στέλνεται.

Κεφαλίδες αιτήματος

Κάθε παράδοση είναι αίτημα POST με Content-Type: application/json και τις εξής κεφαλίδες:

ΚεφαλίδαΠεριεχόμενο
webhook-idΑναγνωριστικό παράδοσης, ίδιο με το id του σώματος. Διατηρείται σε όλες τις επαναλήψεις.
webhook-timestampΧρόνος υπογραφής της συγκεκριμένης προσπάθειας, σε ακέραια δευτερόλεπτα Unix. Ανανεώνεται σε κάθε επανάληψη.
webhook-signatureΠρόθεμα v1, και υπογραφή HMAC-SHA256 σε base64. Υπολογίζεται ξανά σε κάθε επανάληψη.

Δομή δεδομένων

ΠεδίοΤύποςΠεριγραφή
version4Έκδοση της δομής δεδομένων. Μπορεί να προστεθούν πεδία χωρίς αλλαγή έκδοσης· αγνοήστε όσα δεν αναγνωρίζετε. Η έκδοση 2 αντικατέστησε το confidence με το trust και πρόσθεσε το reason. Η έκδοση 3 πρόσθεσε τα findingKind και evidence. Η έκδοση 4 πρόσθεσε τα currency, directPriceMinor, otaPriceMinor και deltaMinor, οπότε ένας δέκτης που δεχόταν μόνο το 3 πρέπει πλέον να δέχεται το 4.
idstringΑναγνωριστικό παράδοσης, ίδιο με το webhook-id. Χρησιμοποιείται για την αποφυγή διπλής επεξεργασίας.
event"disparity.opened"Τύπος συμβάντος.
disparityIdstringΑναγνωριστικό της απόκλισης στο StayParity.
hotel.idstringΑναγνωριστικό ξενοδοχείου στο StayParity.
hotel.namestringΌνομα ξενοδοχείου όπως έχει οριστεί στην εφαρμογή.
otastringΚωδικός καναλιού με πεζούς χαρακτήρες: booking, expedia ή το κανάλι που εμφάνισαν τα αποτελέσματα αναζήτησης, όπως trip ή agoda.
stayDatestringΗμερομηνία διαμονής σε μορφή YYYY-MM-DD.
occupancyintegerΑριθμός ατόμων, από 1 έως 10.
currencystringΝόμισμα του ξενοδοχείου, ως κωδικός ISO 4217, π.χ. EUR ή RON. Σε αυτό εκφράζονται τα directPriceMinor, otaPriceMinor και deltaMinor.
directPriceMinorintegerΗ απευθείας τιμή του ξενοδοχείου, στη μικρότερη υποδιαίρεση του currency.
otaPriceMinorintegerΤιμή καναλιού, στη μικρότερη υποδιαίρεση του currency.
deltaMinorintegerΠόσο λιγότερο χρεώνει το κανάλι, στη μικρότερη υποδιαίρεση του currency.
directPriceEurMinorintegerΗ απευθείας τιμή του ξενοδοχείου, σε λεπτά του ευρώ.
otaPriceEurMinorintegerΤιμή καναλιού σε λεπτά του ευρώ.
deltaEurMinorintegerΠόσο λιγότερο χρεώνει το κανάλι, σε λεπτά του ευρώ.
deltaPctnumberΗ ίδια διαφορά ως ποσοστό της απευθείας τιμής, στρογγυλοποιημένη σε δύο δεκαδικά ψηφία.
trust"seen_twice"Πάντα seen_twice: σε δύο οργανικούς (όχι χορηγούμενους) ελέγχους των αποτελεσμάτων αναζήτησης ξενοδοχείων, με απόσταση τουλάχιστον 30 λεπτών και στην ίδια βάση, η τιμή του ξενοδοχείου και η τιμή του καναλιού έμειναν και οι δύο εντός 1% από τον πρώτο έλεγχο.
reason"now_over_threshold", προαιρετικόΥπάρχει μόνο όταν η απόκλιση ήταν ήδη ανοιχτή κάτω από τα όρια του κανόνα και τα ξεπέρασε αργότερα. Απουσιάζει σε νέα απόκλιση.
findingKind"rate_disparity"Το είδος του ευρήματος. Προς το παρόν πάντα rate_disparity: το ίδιο δωμάτιο, με τους ίδιους όρους, φθηνότερα στο κανάλι.
evidence.openingobjectΤα στοιχεία του πρώτου ελέγχου της απόκλισης: η προσφορά του ξενοδοχείου και του καναλιού, όπως περιγράφονται στα Στοιχεία. Για απόκλιση seen_twice, η πρώτη από τις δύο.
evidence.latestobjectΤα στοιχεία του πιο πρόσφατου ελέγχου της απόκλισης, με την ίδια δομή. Ίδια με το opening μέχρι να την καταγράψει ξανά επόμενος έλεγχος.
detectedAtstringΧρόνος πρώτου εντοπισμού σε UTC, σε μορφή ISO 8601.

Οι τιμές είναι ακέραιοι στη μικρότερη υποδιαίρεση του νομίσματος: τα directPriceMinor, otaPriceMinor και deltaMinor στο νόμισμα του ξενοδοχείου που ορίζει το currency, τα πεδία EurMinor σε λεπτά του ευρώ, όποιο κι αν είναι αυτό το νόμισμα, και το priceMinor κάθε πλευράς των στοιχείων στο νόμισμα που ορίζει το δικό της currency. Έτσι, το 17900 είναι 179,00 € σε EUR και 17.900 ¥ σε JPY, που δεν έχει μικρότερη υποδιαίρεση. Μην τις μετατρέπετε με διαίρεση σε αριθμούς κινητής υποδιαστολής για να τις συγκρίνετε· συγκρίνετε τους ακεραίους.

Στοιχεία

Κάθε έλεγχος έχει δύο πλευρές, direct (η προσφορά του ξενοδοχείου) και seller (η προσφορά του καναλιού), με τα ίδια πεδία. Όσα πεδία δεν δήλωσε η πηγή απουσιάζουν.

ΠεδίοΤύποςΠεριγραφή
priceMinorintegerΗ τιμή όπως τη δήλωσε η πηγή, στη μικρότερη υποδιαίρεση του currency.
currencystringΤο νόμισμα της πηγής, ως κωδικός ISO 4217, π.χ. EUR.
priceEurMinorintegerΗ ίδια τιμή σε λεπτά του ευρώ.
source"booking_engine" ή "google"Πού καταγράφηκε: στο booking engine του ξενοδοχείου (booking_engine, δεν είναι ακόμη ενεργό: σήμερα κάθε απευθείας τιμή προέρχεται από το google) ή στη λίστα τιμών των αποτελεσμάτων αναζήτησης (google: Google Hotels).
placement"organic" ή "ad", προαιρετικόΠού την εμφάνισαν τα αποτελέσματα αναζήτησης: στη λίστα τιμών ή σε χορηγούμενη θέση.
readAtstringΧρόνος καταγραφής σε UTC, σε μορφή ISO 8601.
roomLabelstring, προαιρετικόΤο όνομα του δωματίου όπως το εμφάνισε η πηγή.
roomRefstring, προαιρετικόΟ κωδικός του δωματίου στην πηγή.
roomType.namestring, προαιρετικόΟ τύπος δωματίου του ξενοδοχείου στον οποίο αντιστοιχίστηκε το δωμάτιο, όπως έχει οριστεί στην εφαρμογή.
roomType.rankinteger, προαιρετικόΗ θέση αυτού του τύπου ανάμεσα στους τύπους δωματίων του ξενοδοχείου, από το βασικό δωμάτιο και πάνω: μεγαλύτερη τιμή σημαίνει ανώτερο δωμάτιο.
board"room_only" ή "breakfast", προαιρετικόΤι δήλωσε η πηγή ότι περιλαμβάνει η τιμή: μόνο διαμονή ή και πρωινό.
mappedBoard"room_only" ή "breakfast", προαιρετικόΤι περιλαμβάνει η τιμή σύμφωνα με την αντιστοίχιση δωματίων του ξενοδοχείου: στην πλευρά του ξενοδοχείου, τη διατροφή του τιμολογιακού του πλάνου όταν η πηγή δεν δήλωσε καμία· στην πλευρά του καναλιού, τη διατροφή του πλάνου του ξενοδοχείου στο οποίο αντιστοιχίζεται το πλάνο του καναλιού.
cancellation"free", "no_free_cancellation" ή "unknown"Οι όροι ακύρωσης. unknown όταν η πηγή δεν τους αναφέρει.
freeCancellationUntilstring, προαιρετικόΗ τελευταία ημέρα δωρεάν ακύρωσης, σε μορφή YYYY-MM-DD.
guestsinteger, προαιρετικόΟ αριθμός ενηλίκων για τους οποίους ισχύει η τιμή.
taxesIncludedboolean, προαιρετικόΑν η τιμή περιλαμβάνει φόρους.
linkstring, προαιρετικόΠού οδηγεί η προσφορά. Για το google, η σελίδα όπου οδηγεί η καταχώριση στα αποτελέσματα αναζήτησης ξενοδοχείων, του καναλιού ή του ίδιου του ξενοδοχείου: η τιμή καταγράφηκε στα αποτελέσματα αναζήτησης ξενοδοχείων, όχι εκεί. Για το booking_engine, η σελίδα όπου καταγράφηκε η τιμή, όταν η πηγή τη δίνει.

Παράδειγμα συμβάντος

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

Επαλήθευση της υπογραφής

Ελέγξτε κάθε παράδοση πριν την εμπιστευτείτε. Η υπογραφή αποδεικνύει ότι το σώμα ήρθε από το StayParity με το κλειδί σας και δεν άλλαξε στη διαδρομή. Η χρονική σήμανση εμποδίζει κάποιον να ξαναστείλει μια παράδοση που υπέκλεψε.

Προτιμήστε την επίσημη βιβλιοθήκη Standard Webhooks. Συγκρίνει την υπογραφή σε σταθερό χρόνο και απορρίπτει χρονική σήμανση που απέχει περισσότερο από πέντε λεπτά από το ρολόι σας. Δώστε ολόκληρο το κλειδί, μαζί με το whsec_, και το αρχικό σώμα (raw body): τα ακριβή bytes του αιτήματος πριν από την ανάλυση JSON. Ένα σώμα που αναλύθηκε και σειριοποιήθηκε ξανά δεν θα ταιριάζει με την υπογραφή.

Node.js

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

Υλοποίηση χωρίς βιβλιοθήκη

Αν δεν μπορείτε να προσθέσετε βιβλιοθήκη, ακολουθήστε τα παρακάτω βήματα:

  1. Αφαιρέστε το πρόθεμα whsec_ και αποκωδικοποιήστε το υπόλοιπο κλειδί από base64. Τα bytes που προκύπτουν είναι το κλειδί HMAC.
  2. Συνενώστε webhook-id, webhook-timestamp και το αρχικό σώμα με τελείες: {id}.{timestamp}.{body}.
  3. Υπολογίστε HMAC-SHA256 και κωδικοποιήστε το αποτέλεσμα σε base64.
  4. Η κεφαλίδα webhook-signature περιέχει εγγραφές v1,<signature>, χωρισμένες με κενά. Αποδεχθείτε το αίτημα αν έστω μία έγκυρη εγγραφή v1 ταιριάζει, με σύγκριση σταθερού χρόνου. Σήμερα αποστέλλεται μία εγγραφή.
  5. Απορρίψτε χρονική σήμανση με απόκλιση μεγαλύτερη από πέντε λεπτά, είτε στο παρελθόν είτε στο μέλλον.

Η παρακάτω υλοποίηση TypeScript χρησιμοποιεί μόνο Web Crypto και λειτουργεί σε Node 20+, Bun και Deno:

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

Επαναλήψεις παράδοσης

Το endpoint πρέπει να απαντά εντός 10 δευτερολέπτων. Η απόκριση καθορίζει την επόμενη ενέργεια:

ΑπόκρισηΕνέργεια
Οποιαδήποτε 2xxΕπιτυχής παράδοση. Το σώμα της απόκρισης αγνοείται· αρκεί κενό 200 ή 204.
5xx, λήξη χρόνου ή σφάλμα δικτύουΕπανάληψη, με έως 5 συνολικές προσπάθειες.
3xxΑποτυχία χωρίς επανάληψη. Δεν ακολουθούνται ανακατευθύνσεις. Δηλώστε την τελική διεύθυνση.
4xxΑποτυχία χωρίς επανάληψη. Χρησιμοποιήστε 4xx μόνο για σφάλματα που δεν διορθώνονται με νέα προσπάθεια.

Τα διαστήματα αναμονής είναι περίπου 10, 20, 40 και 80 δευτερόλεπτα, με τυχαία αυξομείωση έως 50%, ώστε να αποφεύγονται ταυτόχρονες επαναλήψεις. Κάθε προσπάθεια υπογράφεται με νέα χρονική σήμανση και διατηρεί το ίδιο webhook-id.

Η σειρά άφιξης δεν είναι εγγυημένη και μια παράδοση μπορεί να παραληφθεί περισσότερες φορές. Για χρονική ταξινόμηση χρησιμοποιήστε το detectedAt. Για διπλές παραδόσεις, εφαρμόστε τους κανόνες της επόμενης ενότητας.

Η διεύθυνση και το κλειδί διαβάζονται ξανά σε κάθε προσπάθεια. Αν αλλάξετε τη διεύθυνση ενώ εκκρεμούν επαναλήψεις, η επόμενη αποστέλλεται στη νέα.

Μετά από 5 αποτυχημένες προσπάθειες, η παράδοση σταματά. Η αιτία εμφανίζεται στις Ρυθμίσεις → Ειδοποιήσεις. Αφού διορθωθεί το πρόβλημα, ένας διαχειριστής μπορεί να επιλέξει Επανάληψη για να σταλεί ξανά η πιο πρόσφατη αποτυχημένη παράδοση, με το ίδιο webhook-id.

Αποφυγή διπλής επεξεργασίας

Η παράδοση γίνεται τουλάχιστον μία φορά (at least once). Μια λήξη χρόνου από τη δική μας πλευρά μπορεί να σημαίνει ότι ο διακομιστής σας έκανε τη δουλειά και η απάντηση χάθηκε· τότε η ίδια παράδοση έρχεται ξανά. Το ίδιο ισχύει για μια παράδοση που στέλνετε ξανά με την Επανάληψη στην εφαρμογή.

Το webhook-id μένει ίδιο σε κάθε επανάληψη μιας παράδοσης. Κρατήστε τα αναγνωριστικά που έχετε επεξεργαστεί, για λίγες ημέρες τουλάχιστον, και όταν ξαναέρθει ένα, απαντήστε 2xx χωρίς να κάνετε ξανά τη δουλειά. Επειδή το αναγνωριστικό βρίσκεται σε κεφαλίδα, μπορείτε να το ελέγξετε πριν αναλύσετε το σώμα.

Σε κάθε προσπάθεια φτιάχνουμε το σώμα ξανά από την απόκλιση όπως είναι εκείνη τη στιγμή. Η ίδια παράδοση, με το ίδιο webhook-id, μπορεί να περιέχει νεότερες τιμές. Αποφύγετε τη διπλή επεξεργασία με βάση το webhook-id· αν αποθηκεύετε το σώμα, κρατήστε το πιο πρόσφατο που λάβατε.

Για μία ενέργεια ανά απόκλιση, αντί ανά παράδοση, χρησιμοποιήστε ως κλειδί το disparityId.

Αντικατάσταση κλειδιού υπογραφής

Στις Ρυθμίσεις → Webhook, επιλέξτε Αντικατάσταση κλειδιού. Το προηγούμενο κλειδί ακυρώνεται αμέσως, χωρίς μεταβατικό διάστημα. Το νέο εμφανίζεται μόνο μία φορά.

Από τη στιγμή που αντικαθιστάτε το κλειδί μέχρι να το βάλετε στον διακομιστή σας, οι παραδόσεις υπογράφονται με το νέο κλειδί και ο διακομιστής σας θα τις απορρίπτει. Αν απαντά 4xx, αυτές οι παραδόσεις δεν επαναλαμβάνονται. Για να μη χαθούν, βάλτε αμέσως το νέο κλειδί στη θέση του ή, όσο κάνετε την αλλαγή, απαντάτε 5xx σε υπογραφή που δεν μπορείτε να επαληθεύσετε, ώστε να τις φέρουν οι επαναλήψεις. Οι επαναλήψεις διαρκούν περίπου δυόμισι λεπτά, μερικές φορές λίγο πάνω από ένα, οπότε καλύπτουν μόνο μια γρήγορη αλλαγή. Για μια παράδοση που αποτύχει παρ’ όλα αυτά, επιλέξτε Επανάληψη στις Ρυθμίσεις → Ειδοποιήσεις μόλις μπει το νέο κλειδί. Στέλνει ξανά την πιο πρόσφατη αποτυχημένη παράδοση.

Αντικαταστήστε το κλειδί όποτε μπορεί να έχει εκτεθεί: σε ένα commit, σε μια γραμμή αρχείου καταγραφής, σε μια κοινή οθόνη.

Δοκιμή του endpoint

Δεν υπάρχει ακόμη κουμπί δοκιμαστικής αποστολής στην εφαρμογή. Για να δοκιμάσετε το endpoint, υπογράψτε μόνοι σας το παράδειγμα με το κλειδί σας και στείλτε το, ακριβώς όπως θα το στέλναμε εμείς. Αποθηκεύστε το παράδειγμα συμβάντος ως event.json και εκτελέστε:

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

Ελέγξτε και τις περιπτώσεις αποτυχίας. Τροποποιήστε έναν χαρακτήρα του σώματος χωρίς νέα υπογραφή: το αίτημα πρέπει να απορριφθεί. Στείλτε ξανά το ίδιο αναγνωριστικό: το endpoint πρέπει να απαντήσει χωρίς να εκτελέσει ξανά την ενέργεια.

Για τοπικό endpoint, χρησιμοποιήστε tunnel με δημόσιο όνομα https://, γιατί στέλνουμε μόνο σε δημόσιες διευθύνσεις.

Αντιμετώπιση προβλημάτων

Στις Ρυθμίσεις → Ειδοποιήσεις, κάτω από τη διεύθυνση webhook του ξενοδοχείου, εμφανίζεται η τελευταία επιτυχής παράδοση ή η αιτία αποτυχίας:

  • Χωρίς κλειδί υπογραφής: ο λογαριασμός δεν έχει ακόμη κλειδί. Δημιουργήστε το στις Ρυθμίσεις → Webhook.
  • Απορρίφθηκε: το endpoint απάντησε 3xx ή 4xx, ή η διεύθυνση δεν επιτρέπεται πλέον.
  • Μη προσβάσιμο: απέτυχαν 5 προσπάθειες λόγω λήξης χρόνου, απόκρισης 5xx ή προβλήματος σύνδεσης.
  • Δεν έχει οριστεί webhook: η διεύθυνση αφαιρέθηκε ή η Αποστολή ειδοποιήσεων απενεργοποιήθηκε, ενώ η παράδοση ήταν ήδη προγραμματισμένη.

Αφού διορθώσετε την αιτία, η Επανάληψη δίπλα της στέλνει ξανά την πιο πρόσφατη αποτυχημένη παράδοση.

Αν αποτυγχάνει η επαλήθευση υπογραφής:

  • Βεβαιωθείτε ότι χρησιμοποιείτε το αρχικό σώμα, πριν από ανάλυση JSON.
  • Ελέγξτε ότι το κλειδί είναι το πιο πρόσφατο, μετά από τυχόν Αντικατάσταση κλειδιού.
  • Δώστε στη βιβλιοθήκη ολόκληρο το whsec_…, χωρίς επιπλέον κενά.
  • Συγχρονίστε το ρολόι του διακομιστή με NTP. Απόκλιση άνω των πέντε λεπτών απορρίπτεται.

Αν δεν παραλαμβάνεται κανένα συμβάν:

  • Ελέγξτε αν οι ειδοποιήσεις είναι ενεργές και αν έχει εντοπιστεί απόκλιση που καλύπτει τα ελάχιστα όρια.
  • Ελέγξτε αν οι αποκλίσεις αφορούν κανάλια που δεν παρακολουθεί το ξενοδοχείο ή αν είναι ευρήματα «Φθηνότερα στην αναζήτηση», που δεν δημιουργούν ποτέ συμβάν.
  • Εξετάστε τους κανόνες του firewall. Δεν δημοσιεύεται σταθερή λίστα διευθύνσεων IP· χρησιμοποιήστε την υπογραφή για επαλήθευση της προέλευσης.

Σε αυτή τη σελίδα