Webhooks
Το υπογεγραμμένο συμβάν JSON που στέλνει το StayParity όταν ένα OTA πουλάει κάτω από την απευθείας τιμή ενός ξενοδοχείου. Υπογραφές, επαναλήψεις, δοκιμές.
Το StayParity στέλνει κάθε νέα απόκλιση τιμής στον διακομιστή σας ως JSON: ένα κανάλι στα αποτελέσματα αναζήτησης ξενοδοχείων πουλάει το ίδιο δωμάτιο με το ξενοδοχείο, με αντιστοίχιση και των δύο σε έναν από τους τύπους δωματίων του ξενοδοχείου, φθηνότερα από την ιστοσελίδα του ξενοδοχείου. Χρησιμοποιήστε το για να ανοίξετε ένα αίτημα υποστήριξης, να στείλετε μήνυμα στον υπεύθυνο εσόδων ή να τροφοδοτήσετε τον δικό σας πίνακα ελέγχου.
Οι παραδόσεις ακολουθούν το Standard Webhooks και επαληθεύονται με τις αντίστοιχες βιβλιοθήκες. Η δομή περιγράφεται και στην προδιαγραφή OpenAPI 3.1.
Ρύθμιση του endpoint
Η ρύθμιση γίνεται σε τρία βήματα:
- Δημιουργήστε κλειδί υπογραφής. Στην εφαρμογή, ανοίξτε τις Ρυθμίσεις → Webhook και επιλέξτε Δημιουργία κλειδιού. Το κλειδί έχει πρόθεμα
whsec_και εμφανίζεται μόνο μία φορά. Αποθηκεύστε το στις ρυθμίσεις του διακομιστή πριν κλείσετε το παράθυρο. Το ίδιο κλειδί υπογράφει τις παραδόσεις όλων των ξενοδοχείων του λογαριασμού. - Ορίστε τη διεύθυνση αποστολής. Στις Ρυθμίσεις → Ειδοποιήσεις, με επιλεγμένο το ξενοδοχείο, επιλέξτε Προσθήκη στην ενότητα Πού στέλνεται η ειδοποίηση (ή Ρύθμιση ειδοποιήσεων, αν το ξενοδοχείο δεν έχει ακόμη κανόνα) και συμπληρώστε το URL του webhook. Κάθε ξενοδοχείο μπορεί να έχει διαφορετική διεύθυνση. Κενό πεδίο απενεργοποιεί τα webhooks για το συγκεκριμένο ξενοδοχείο.
- Επιστρέψτε απόκριση 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. Υπολογίζεται ξανά σε κάθε επανάληψη. |
Δομή δεδομένων
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
version | 4 | Έκδοση της δομής δεδομένων. Μπορεί να προστεθούν πεδία χωρίς αλλαγή έκδοσης· αγνοήστε όσα δεν αναγνωρίζετε. Η έκδοση 2 αντικατέστησε το confidence με το trust και πρόσθεσε το reason. Η έκδοση 3 πρόσθεσε τα findingKind και evidence. Η έκδοση 4 πρόσθεσε τα currency, directPriceMinor, otaPriceMinor και deltaMinor, οπότε ένας δέκτης που δεχόταν μόνο το 3 πρέπει πλέον να δέχεται το 4. |
id | string | Αναγνωριστικό παράδοσης, ίδιο με το webhook-id. Χρησιμοποιείται για την αποφυγή διπλής επεξεργασίας. |
event | "disparity.opened" | Τύπος συμβάντος. |
disparityId | string | Αναγνωριστικό της απόκλισης στο StayParity. |
hotel.id | string | Αναγνωριστικό ξενοδοχείου στο StayParity. |
hotel.name | string | Όνομα ξενοδοχείου όπως έχει οριστεί στην εφαρμογή. |
ota | string | Κωδικός καναλιού με πεζούς χαρακτήρες: booking, expedia ή το κανάλι που εμφάνισαν τα αποτελέσματα αναζήτησης, όπως trip ή agoda. |
stayDate | string | Ημερομηνία διαμονής σε μορφή YYYY-MM-DD. |
occupancy | integer | Αριθμός ατόμων, από 1 έως 10. |
currency | string | Νόμισμα του ξενοδοχείου, ως κωδικός ISO 4217, π.χ. EUR ή RON. Σε αυτό εκφράζονται τα directPriceMinor, otaPriceMinor και deltaMinor. |
directPriceMinor | integer | Η απευθείας τιμή του ξενοδοχείου, στη μικρότερη υποδιαίρεση του currency. |
otaPriceMinor | integer | Τιμή καναλιού, στη μικρότερη υποδιαίρεση του currency. |
deltaMinor | integer | Πόσο λιγότερο χρεώνει το κανάλι, στη μικρότερη υποδιαίρεση του currency. |
directPriceEurMinor | integer | Η απευθείας τιμή του ξενοδοχείου, σε λεπτά του ευρώ. |
otaPriceEurMinor | integer | Τιμή καναλιού σε λεπτά του ευρώ. |
deltaEurMinor | integer | Πόσο λιγότερο χρεώνει το κανάλι, σε λεπτά του ευρώ. |
deltaPct | number | Η ίδια διαφορά ως ποσοστό της απευθείας τιμής, στρογγυλοποιημένη σε δύο δεκαδικά ψηφία. |
trust | "seen_twice" | Πάντα seen_twice: σε δύο οργανικούς (όχι χορηγούμενους) ελέγχους των αποτελεσμάτων αναζήτησης ξενοδοχείων, με απόσταση τουλάχιστον 30 λεπτών και στην ίδια βάση, η τιμή του ξενοδοχείου και η τιμή του καναλιού έμειναν και οι δύο εντός 1% από τον πρώτο έλεγχο. |
reason | "now_over_threshold", προαιρετικό | Υπάρχει μόνο όταν η απόκλιση ήταν ήδη ανοιχτή κάτω από τα όρια του κανόνα και τα ξεπέρασε αργότερα. Απουσιάζει σε νέα απόκλιση. |
findingKind | "rate_disparity" | Το είδος του ευρήματος. Προς το παρόν πάντα rate_disparity: το ίδιο δωμάτιο, με τους ίδιους όρους, φθηνότερα στο κανάλι. |
evidence.opening | object | Τα στοιχεία του πρώτου ελέγχου της απόκλισης: η προσφορά του ξενοδοχείου και του καναλιού, όπως περιγράφονται στα Στοιχεία. Για απόκλιση seen_twice, η πρώτη από τις δύο. |
evidence.latest | object | Τα στοιχεία του πιο πρόσφατου ελέγχου της απόκλισης, με την ίδια δομή. Ίδια με το opening μέχρι να την καταγράψει ξανά επόμενος έλεγχος. |
detectedAt | string | Χρόνος πρώτου εντοπισμού σε UTC, σε μορφή ISO 8601. |
Οι τιμές είναι ακέραιοι στη μικρότερη υποδιαίρεση του νομίσματος: τα directPriceMinor, otaPriceMinor και deltaMinor στο νόμισμα του ξενοδοχείου που ορίζει το currency, τα πεδία EurMinor σε λεπτά του ευρώ, όποιο κι αν είναι αυτό το νόμισμα, και το priceMinor κάθε πλευράς των στοιχείων στο νόμισμα που ορίζει το δικό της currency. Έτσι, το 17900 είναι 179,00 € σε EUR και 17.900 ¥ σε JPY, που δεν έχει μικρότερη υποδιαίρεση. Μην τις μετατρέπετε με διαίρεση σε αριθμούς κινητής υποδιαστολής για να τις συγκρίνετε· συγκρίνετε τους ακεραίους.
Στοιχεία
Κάθε έλεγχος έχει δύο πλευρές, direct (η προσφορά του ξενοδοχείου) και seller (η προσφορά του καναλιού), με τα ίδια πεδία. Όσα πεδία δεν δήλωσε η πηγή απουσιάζουν.
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
priceMinor | integer | Η τιμή όπως τη δήλωσε η πηγή, στη μικρότερη υποδιαίρεση του currency. |
currency | string | Το νόμισμα της πηγής, ως κωδικός ISO 4217, π.χ. EUR. |
priceEurMinor | integer | Η ίδια τιμή σε λεπτά του ευρώ. |
source | "booking_engine" ή "google" | Πού καταγράφηκε: στο booking engine του ξενοδοχείου (booking_engine, δεν είναι ακόμη ενεργό: σήμερα κάθε απευθείας τιμή προέρχεται από το google) ή στη λίστα τιμών των αποτελεσμάτων αναζήτησης (google: Google Hotels). |
placement | "organic" ή "ad", προαιρετικό | Πού την εμφάνισαν τα αποτελέσματα αναζήτησης: στη λίστα τιμών ή σε χορηγούμενη θέση. |
readAt | string | Χρόνος καταγραφής σε UTC, σε μορφή ISO 8601. |
roomLabel | string, προαιρετικό | Το όνομα του δωματίου όπως το εμφάνισε η πηγή. |
roomRef | string, προαιρετικό | Ο κωδικός του δωματίου στην πηγή. |
roomType.name | string, προαιρετικό | Ο τύπος δωματίου του ξενοδοχείου στον οποίο αντιστοιχίστηκε το δωμάτιο, όπως έχει οριστεί στην εφαρμογή. |
roomType.rank | integer, προαιρετικό | Η θέση αυτού του τύπου ανάμεσα στους τύπους δωματίων του ξενοδοχείου, από το βασικό δωμάτιο και πάνω: μεγαλύτερη τιμή σημαίνει ανώτερο δωμάτιο. |
board | "room_only" ή "breakfast", προαιρετικό | Τι δήλωσε η πηγή ότι περιλαμβάνει η τιμή: μόνο διαμονή ή και πρωινό. |
mappedBoard | "room_only" ή "breakfast", προαιρετικό | Τι περιλαμβάνει η τιμή σύμφωνα με την αντιστοίχιση δωματίων του ξενοδοχείου: στην πλευρά του ξενοδοχείου, τη διατροφή του τιμολογιακού του πλάνου όταν η πηγή δεν δήλωσε καμία· στην πλευρά του καναλιού, τη διατροφή του πλάνου του ξενοδοχείου στο οποίο αντιστοιχίζεται το πλάνο του καναλιού. |
cancellation | "free", "no_free_cancellation" ή "unknown" | Οι όροι ακύρωσης. unknown όταν η πηγή δεν τους αναφέρει. |
freeCancellationUntil | string, προαιρετικό | Η τελευταία ημέρα δωρεάν ακύρωσης, σε μορφή YYYY-MM-DD. |
guests | integer, προαιρετικό | Ο αριθμός ενηλίκων για τους οποίους ισχύει η τιμή. |
taxesIncluded | boolean, προαιρετικό | Αν η τιμή περιλαμβάνει φόρους. |
link | string, προαιρετικό | Πού οδηγεί η προσφορά. Για το google, η σελίδα όπου οδηγεί η καταχώριση στα αποτελέσματα αναζήτησης ξενοδοχείων, του καναλιού ή του ίδιου του ξενοδοχείου: η τιμή καταγράφηκε στα αποτελέσματα αναζήτησης ξενοδοχείων, όχι εκεί. Για το booking_engine, η σελίδα όπου καταγράφηκε η τιμή, όταν η πηγή τη δίνει. |
Παράδειγμα συμβάντος
{
"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 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);Υλοποίηση χωρίς βιβλιοθήκη
Αν δεν μπορείτε να προσθέσετε βιβλιοθήκη, ακολουθήστε τα παρακάτω βήματα:
- Αφαιρέστε το πρόθεμα
whsec_και αποκωδικοποιήστε το υπόλοιπο κλειδί από base64. Τα bytes που προκύπτουν είναι το κλειδί HMAC. - Συνενώστε
webhook-id,webhook-timestampκαι το αρχικό σώμα με τελείες:{id}.{timestamp}.{body}. - Υπολογίστε HMAC-SHA256 και κωδικοποιήστε το αποτέλεσμα σε base64.
- Η κεφαλίδα
webhook-signatureπεριέχει εγγραφέςv1,<signature>, χωρισμένες με κενά. Αποδεχθείτε το αίτημα αν έστω μία έγκυρη εγγραφήv1ταιριάζει, με σύγκριση σταθερού χρόνου. Σήμερα αποστέλλεται μία εγγραφή. - Απορρίψτε χρονική σήμανση με απόκλιση μεγαλύτερη από πέντε λεπτά, είτε στο παρελθόν είτε στο μέλλον.
Η παρακάτω υλοποίηση TypeScript χρησιμοποιεί μόνο Web Crypto και λειτουργεί σε Node 20+, Bun και Deno:
// 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 και εκτελέστε:
// 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· χρησιμοποιήστε την υπογραφή για επαλήθευση της προέλευσης.
Τεχνική τεκμηρίωση
Πώς συνδέετε το StayParity με τα δικά σας συστήματα. Υπογεγραμμένα webhook, το widget απευθείας κρατήσεων και το API ελέγχου τιμών για chatbot.
Widget κρατήσεων
Ενσωματώστε το widget απευθείας κρατήσεων του StayParity σε ιστοσελίδα ξενοδοχείου με έναν κώδικα. Ο κώδικας, το dock, τι βλέπουν οι επισκέπτες και το CSP.