Webhooks

Τα webhooks στέλνουν ένα αίτημα HTTP POST στο σύστημά σας όταν συμβαίνει ένα συμβάν ουράς. Τα συμβάντα περιλαμβάνουν την είσοδο ενός εισιτηρίου σε ουρά, την κλήση του και την ολοκλήρωσή του.

Ξεκινώντας

Ανοίξτε το admin.jonot.io/settings/integrations.
Κάντε κλικ στο Προσθήκη τελικού σημείου.
Εισαγάγετε μια δημόσια διεύθυνση URL HTTPS που δέχεται αιτήματα στον διακομιστή σας.
Επιλέξτε σε ποια συμβάντα θα εγγραφείτε.
Κάντε κλικ στο Αποθήκευση τελικού σημείου.

Αντιγράψτε και φυλάξτε το μυστικό υπογραφής μόλις εμφανιστεί. Το Jonot το δείχνει μόνο μία φορά. Για να ελέγξετε ότι το Jonot φτάνει στο τελικό σημείο σας, χρησιμοποιήστε το κουμπί Αποστολή δοκιμαστικού αιτήματος στη σελίδα επεξεργασίας τελικού σημείου.

Τύποι συμβάντων

Όνομα συμβάντος	Πότε το στέλνει το Jonot
`ticket.joined`	Ένας πελάτης μπαίνει σε μια ουρά
`ticket.called`	Ένα μέλος προσωπικού καλεί ένα εισιτήριο στον σταθμό εξυπηρέτησης
`ticket.completed`	Ένα εισιτήριο σημειώνεται ως ολοκληρωμένο
`ticket.cancelled`	Ένας πελάτης ή μέλος προσωπικού ακυρώνει ένα εισιτήριο
`ticket.skipped`	Ένα εισιτήριο παραλείπεται (μια ανακλητή αναβολή)
`ticket.no_show`	Ένα κληθέν ή παραλειφθέν εισιτήριο επιβεβαιώνεται ως μη εμφάνιση
`queue.status_changed`	Η κατάσταση μιας ουράς αλλάζει (`ACTIVE`, `PAUSED`, ή `CLOSED`)

Μορφή payload

Κάθε παράδοση είναι ένα HTTP POST με:

Content-Type: application/json
X-Jonot-Event: ticket.called
X-Jonot-Delivery-Id: <uuid>
X-Jonot-Timestamp: 2024-06-01T12:00:00.000Z
X-Jonot-Signature: v1,<base64-hmac-sha256>
X-Jonot-Payload-Version: v1

Το προεπιλεγμένο σώμα είναι ένα αντικείμενο JSON. Το περιεχόμενο του πεδίου payload εξαρτάται από το συμβάν:

ticket.joined

{
  "deliveryId": "<uuid>",
  "event": "ticket.joined",
  "timestamp": "2024-06-01T12:00:00.000Z",
  "org": { "id": "org_…", "name": "My Org" },
  "payload": {
    "ticket": { "id": "tkt_…", "queueId": "q_…" },
    "queue": { "id": "q_…", "name": "Main Queue" },
    "location": { "id": "loc_…", "name": "Downtown" }
  }
}

ticket.called / ticket.completed / ticket.skipped / ticket.no_show

{
  "deliveryId": "<uuid>",
  "event": "ticket.called",
  "timestamp": "2024-06-01T12:00:00.000Z",
  "org": { "id": "org_…", "name": "My Org" },
  "payload": {
    "ticket": {
      "id": "tkt_…",
      "number": 42,
      "status": "CALLED",
      "queueId": "q_…",
      "createdAt": "2024-06-01T11:58:00.000Z",
      "updatedAt": "2024-06-01T12:00:00.000Z"
    }
  }
}

ticket.cancelled

{
  "deliveryId": "<uuid>",
  "event": "ticket.cancelled",
  "timestamp": "2024-06-01T12:00:00.000Z",
  "org": { "id": "org_…", "name": "My Org" },
  "payload": {
    "ticketId": "tkt_…",
    "queueId": "q_…"
  }
}

queue.status_changed

{
  "deliveryId": "<uuid>",
  "event": "queue.status_changed",
  "timestamp": "2024-06-01T12:00:00.000Z",
  "org": { "id": "org_…", "name": "My Org" },
  "payload": {
    "queueId": "q_…",
    "status": "PAUSED"
  }
}

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

Το Jonot υπογράφει κάθε παράδοση με HMAC-SHA256 πάνω στη συμβολοσειρά:

<deliveryId>.<timestamp>.<body>

Για επαλήθευση σε Node.js (≥18):

import { createHmac, timingSafeEqual } from "node:crypto";

/**
 * Επιστρέφει true όταν η κεφαλίδα υπογραφής είναι έγκυρη και η χρονοσφραγίδα
 * είναι εντός 5 λεπτών από τώρα. Πετάει σφάλμα για κακοσχηματισμένη είσοδο.
 */
function verifySignature(secret, deliveryId, timestamp, body, header) {
  // Προστασία από επίθεση επανάληψης: απόρριψη παραδόσεων παλαιότερων των 5 λεπτών.
  const ageMs = Date.now() - new Date(timestamp).getTime();
  if (Math.abs(ageMs) > 5 * 60 * 1000) return false;

  const expected =
    "v1," +
    createHmac("sha256", secret)
      .update(`${deliveryId}.${timestamp}.${body}`)
      .digest("base64");

  // Το timingSafeEqual αποτρέπει επιθέσεις timing-oracle.
  // Τα Buffer πρέπει να έχουν το ίδιο μήκος — αν τα μήκη διαφέρουν η υπογραφή
  // είναι άκυρη, αλλά συγκρίνουμε ακόμα μια εικονική τιμή για να διατηρηθεί ο σταθερός χρόνος.
  const expectedBuf = Buffer.from(expected);
  const headerBuf = Buffer.from(header);
  if (expectedBuf.length !== headerBuf.length) return false;
  return timingSafeEqual(expectedBuf, headerBuf);
}

Πρότυπα payload

Μπορείτε να αντικαταστήσετε το προεπιλεγμένο σώμα JSON με ένα δικό σας πρότυπο. Τα πρότυπα χρησιμοποιούν αυτή τη σύνταξη Mustache-lite:

{{ path.to.value }} — το Jonot εισάγει την τιμή και εφαρμόζει χαρακτήρες διαφυγής ανάλογα με τον τύπο περιεχομένου. Χρησιμοποιεί διαφυγή συμβολοσειράς JSON για application/json, κωδικοποίηση ποσοστού για application/x-www-form-urlencoded, και καμία διαφυγή για text/plain.
{{{ path.to.value }}} — το Jonot εισάγει την τιμή χωρίς χαρακτήρες διαφυγής.

Παράδειγμα προτύπου για application/json (εγγεγραμμένο στο ticket.joined):

{
  "type": "{{ event }}",
  "ticketId": "{{ payload.ticket.id }}",
  "queueName": "{{ payload.queue.name }}"
}

Επεξεργαστής προτύπου

Το πεδίο προτύπου payload είναι ένας πλήρης επεξεργαστής κώδικα με:

Επισήμανση σύνταξης και αντιστοίχιση αγκυλών για πρότυπα JSON.
Λίστα μεταβλητών — μια σειρά κουμπιών για τις διαδρομές μεταβλητών που είναι διαθέσιμες στα συμβάντα που επιλέξατε. Κάντε κλικ σε ένα κουμπί για να εισαγάγετε ένα token {{ path }} στη θέση του δρομέα.
Ζωντανή επικύρωση — καθώς πληκτρολογείτε, ο επεξεργαστής ελέγχει τις διαδρομές μεταβλητών. Ελέγχει επίσης τη δομή JSON, όταν ο τύπος περιεχομένου είναι application/json και το πρότυπο δεν έχει ετικέτες {{{ }}}. Ο επεξεργαστής σημειώνει τα προβλήματα μέσα στον κώδικα και τα παραθέτει από κάτω:
- Σφάλμα — μια διαδρομή που είναι άγνωστη σε όλα τα συμβάντα που επιλέξατε.
- Προειδοποίηση — μια διαδρομή που υπάρχει μόνο σε ορισμένα από τα συμβάντα που επιλέξατε (θα είναι κενή στις παραδόσεις των υπόλοιπων).

Ο διακομιστής εφαρμόζει τους ίδιους κανόνες επικύρωσης όταν αποθηκεύετε.

Επανάληψη παραδόσεων

Τα Cloudflare Queues επαναλαμβάνουν μια αποτυχημένη παράδοση έως 3 φορές, με μεγαλύτερη καθυστέρηση πριν από κάθε επανάληψη. Μια παράδοση αποτυγχάνει όταν το τελικό σημείο επιστρέφει κατάσταση εκτός του εύρους 2xx ή όταν υπάρχει σφάλμα σύνδεσης. Αν αποτύχουν η αρχική προσπάθεια και οι 3 επαναλήψεις, η παράδοση περνά στην ουρά dead-letter και ο μετρητής διαδοχικών αποτυχιών του τελικού σημείου αυξάνεται.

Το Jonot απενεργοποιεί αυτόματα ένα τελικό σημείο μετά από 20 διαδοχικές αποτυχίες. Μπορείτε να το ενεργοποιήσετε ξανά από τη σελίδα επεξεργασίας τελικού σημείου. Έτσι ο μετρητής μηδενίζεται.

Ιστορικό παραδόσεων

Η καρτέλα Παραδόσεις κάθε τελικού σημείου δείχνει τις προσπάθειες παράδοσης των τελευταίων 30 ημερών. Κάθε εγγραφή περιλαμβάνει τον τύπο του συμβάντος, την κατάσταση HTTP, τον αριθμό προσπαθειών και την ώρα. Χρησιμοποιήστε το κουμπί Φόρτωση περισσότερων για να δείτε παλαιότερες εγγραφές μέσα σε αυτό το διάστημα.

Όρια

Όριο	Τιμή
Τελικά σημεία ανά οργανισμό	5
Προσαρμοσμένες κεφαλίδες ανά τελικό σημείο	10
Μήκος τιμής κεφαλίδας	1.024 bytes
Μέγεθος προτύπου payload	16 KB
Χρονικό όριο παράδοσης	10 δ.
Διατήρηση ιστορικού παραδόσεων	30 ημέρες
Μέγιστος ρυθμός παράδοσης ανά οργανισμό	120 / 60 δ.

Εναλλαγή του μυστικού υπογραφής

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

Το παλιό και το νέο μυστικό δεν ισχύουν ταυτόχρονα. Το παλιό μυστικό σταματά να επαληθεύει αιτήματα μόλις επιβεβαιώσετε την εναλλαγή. Ενημερώστε αμέσως μετά το σύστημα που λαμβάνει τα webhooks σας.

Η διεπαφή εμφανίζει Ενεργό μυστικό: ····XXXX δίπλα στο κουμπί Εναλλαγή. Οι τελευταίοι τέσσερις χαρακτήρες σας βοηθούν να επιβεβαιώσετε ποιο μυστικό ισχύει μετά από μια εναλλαγή.

Καλές πρακτικές για το μυστικό υπογραφής

Πότε να εναλλάξετε:

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

Πώς να ενημερώσετε το σύστημα λήψης:

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

Αν χάσατε το νέο μυστικό πριν το αποθηκεύσετε:

Κάντε ξανά εναλλαγή. Κάθε εναλλαγή δημιουργεί ένα νέο τυχαίο μυστικό. Το Jonot δεν μπορεί να ανακτήσει την προηγούμενη αναγνώσιμη τιμή, επειδή ο διακομιστής αποθηκεύει μόνο μια κρυπτογραφημένη μορφή.