Λάβετε συμβάντα TicketWave ως υπογεγραμμένα αιτήματα HTTP στη δική σας εφαρμογή.

Webhooks

Ένα webhook είναι ένα αίτημα HTTP που σας στέλνει το TicketWave. Κάθε φορά που συμβαίνει κάτι στον διακομιστή σας — ανοίγει ένα ticket, ένα μέλος μπαίνει στη μαύρη λίστα — το TicketWave κάνει POST ένα σώμα JSON σε ένα URL που ελέγχετε εσείς.

Αυτή είναι η διαφορά σε σχέση με τα Log Channels: τα log channels γράφουν ένα embed στο Discord για να το διαβάζουν άνθρωποι, ενώ τα webhooks παραδίδουν το ακατέργαστο συμβάν στον κώδικά σας.

Τα webhooks είναι λειτουργία premium. Χωρίς premium, δεν μπορούν να δημιουργηθούν endpoints και δεν παραδίδονται συμβάντα.

Δημιουργία Endpoint

Ανοίξτε τη σελίδα endpoints

Πίνακας ελέγχου διακομιστή → Webhooks → Endpoints.

Προσθέστε ένα endpoint

Κάντε κλικ στο Add Endpoint και συμπληρώστε δύο πεδία:

Field	Description
Endpoint URL	Το URL `https://` που λαμβάνει τα αιτήματα
Event Types	Ποια συμβάντα πρέπει να λαμβάνει αυτό το endpoint

Ένα endpoint λαμβάνει μόνο τους τύπους που επιλέγετε. Δεν επιτρέπεται να μην επιλέξετε κανέναν — επιλέξτε τουλάχιστον έναν.

Αντιγράψτε το signing secret

Το TicketWave δημιουργεί ένα signing secret (whsec_…) τη στιγμή που δημιουργείται το endpoint. Ανοίξτε τη λίστα endpoints, αποκαλύψτε το με το εικονίδιο του ματιού και αντιγράψτε το στη ρύθμιση της εφαρμογής σας.

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

Στείλτε ένα δοκιμαστικό συμβάν

Χρησιμοποιήστε το κουμπί Send test event (το χάρτινο αεροπλανάκι) στη γραμμή του endpoint. Στέλνει ένα πραγματικό, πλήρως υπογεγραμμένο αίτημα με "test": true στο payload, ώστε να επιβεβαιώσετε ότι ο δέκτης σας λειτουργεί πριν εξαρτηθεί από αυτόν ένα πραγματικό ticket.

Το αποτέλεσμα εμφανίζεται στο ιστορικό Webhooks όπως κάθε άλλη παράδοση.

Απαιτήσεις Endpoint

Requirement	Detail
Scheme	Μόνο `https://` — το `http://` απορρίπτεται
Host	Πρέπει να επιλύεται δημόσια. Ιδιωτικές, loopback, link-local και διευθύνσεις CGNAT απορρίπτονται
Response	Οποιαδήποτε κατάσταση `2xx` μετρά ως επιτυχία
Timeout	Έχετε 10 δευτερόλεπτα για να απαντήσετε
Redirects	Δεν ακολουθούνται. Ένα `3xx` μετρά ως αποτυχία
Limit	Έως 5 endpoints ανά διακομιστή

Ο έλεγχος του host γίνεται τόσο όταν αποθηκεύετε το endpoint όσο και πριν από κάθε μεμονωμένη παράδοση, οπότε ένας τομέας που αργότερα αρχίζει να επιλύεται σε εσωτερική διεύθυνση σταματά να δέχεται παραδόσεις.

Το Αίτημα

Κάθε παράδοση είναι ένα POST με σώμα JSON.

Headers

Header	Example	Meaning
`Content-Type`	`application/json`	Πάντα JSON
`User-Agent`	`TicketWave-Webhooks/1.0.5`	Η έκδοση του bot που το έστειλε
`X-TicketWave-Event`	`ticket.created`	Ο τύπος συμβάντος
`X-TicketWave-Delivery`	`wh_3f2a…`	Μοναδικό id για αυτή την παράδοση
`X-TicketWave-Timestamp`	`1786224191`	Unix seconds, μέρος της υπογραφής
`X-TicketWave-Signature`	`sha256=9f86d0…`	HMAC του αιτήματος

Body

Κάθε payload χρησιμοποιεί το ίδιο περίβλημα. Μόνο το data διαφέρει ανά τύπο συμβάντος:

{
  "event": "ticket.created",
  "timestamp": "2026-08-26T08:23:11.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1042",
    "ticket_num_id": 1042,
    "channel_id": "998877665544332211",
    "category": "🤖 Support",
    "user": { "id": "987654321098765432", "username": "Luna" },
    "created_at": "2026-08-26T08:23:11.000Z"
  }
}

Δείτε το Event Reference για το αντικείμενο data κάθε τύπου.

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

Όποιος ανακαλύψει το URL του endpoint σας μπορεί να του στείλει ένα αίτημα POST. Η υπογραφή είναι ο τρόπος με τον οποίο ξεχωρίζετε μια πραγματική παράδοση TicketWave από μια πλαστογραφημένη.

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

Πώς δημιουργείται η υπογραφή

Το TicketWave ενώνει το timestamp και το ακατέργαστο σώμα του αιτήματος με μια τελεία και εκτελεί HMAC-SHA256 στο αποτέλεσμα χρησιμοποιώντας το secret του endpoint σας:

signed_payload = X-TicketWave-Timestamp + "." + raw_request_body
signature      = HMAC_SHA256(signed_payload, your_endpoint_secret)

Το header μεταφέρει αυτό το digest σε hex μορφή και με πρόθεμα: sha256=<digest>.

Τι πρέπει να κάνει ο δέκτης σας

Διαβάστε το ακατέργαστο body. Επαληθεύστε με βάση τα ακριβή bytes που λάβατε. Αν το framework σας κάνει πρώτα parse το JSON και μετά το ξανα-serialise, η σειρά των κλειδιών ή τα κενά μπορεί να αλλάξουν και το digest δεν θα ταιριάξει.

Υπολογίστε ξανά το HMAC πάνω στο timestamp + "." + rawBody με το secret σας.

Συγκρίνετε σε σταθερό χρόνο (crypto.timingSafeEqual στο Node). Ένα απλό === διαρρέει πληροφορίες χρονισμού.

Ελέγξτε ότι το timestamp είναι πρόσφατο — πέντε λεπτά ανοχής είναι μια καλή προεπιλογή. Το timestamp βρίσκεται μέσα στο υπογεγραμμένο payload, άρα ένας επιτιθέμενος δεν μπορεί να επαναλάβει ένα παλιό αίτημα με φρέσκο timestamp.

Μια πλήρης υλοποίηση υπάρχει στη σελίδα Example Server.

Επαναπροσπάθειες

Μια παράδοση που αποτυγχάνει επαναλαμβάνεται αυτόματα.


Attempts	3 (η πρώτη προσπάθεια συν 2 επαναπροσπάθειες)
Backoff	1 δευτερόλεπτο, μετά 5 δευτερόλεπτα
Retried on	Σφάλματα δικτύου, timeouts, `408`, `429` και οποιοδήποτε `5xx`
Not retried on	Κάθε άλλο `4xx` — αυτά σημαίνουν ότι το endpoint σας απέρριψε το αίτημα επίτηδες

Λόγω των επαναπροσπαθειών, το endpoint σας μπορεί να λάβει το ίδιο συμβάν δύο φορές. Χρησιμοποιήστε το X-TicketWave-Delivery ως idempotency key: θυμηθείτε τα ids που έχετε επεξεργαστεί και αγνοήστε τις επαναλήψεις.

Οι παραδόσεις δεν είναι ταξινομημένες. Αν δημιουργηθούν δύο tickets την ίδια στιγμή, τα αιτήματα μπορούν να φτάσουν με οποιαδήποτε σειρά — χρησιμοποιήστε το πεδίο timestamp στο body αν η σειρά σας ενδιαφέρει.

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

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

Οι αποτυχημένες παραδόσεις μπορούν να σταλούν ξανά από τη σελίδα λεπτομερειών με το Retry Webhook. Στέλνει ξανά το αρχικό payload στο ίδιο endpoint και καταγράφει μια νέα παράδοση.

Το ιστορικό διατηρείται για 30 ημέρες, και μετά καθαρίζεται αυτόματα.

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

Problem	Fix
Το endpoint δεν μπορεί να αποθηκευτεί	Το URL πρέπει να είναι `https://` και να επιλύεται σε δημόσια διεύθυνση
Όλα εμφανίζονται ως αποτυχημένα χωρίς κωδικό απόκρισης	Το αίτημα δεν έφτασε ποτέ σε εσάς — timeout, αποτυχία DNS ή connection refused
Η υπογραφή δεν ταιριάζει ποτέ	Κάνετε hash στο parsed body αντί για τα ακατέργαστα bytes ή ξεχάσατε το πρόθεμα `timestamp + "."`
Οι παραδόσεις σταματούν μετά από λίγο	Ελέγξτε αν ο host σας άρχισε να επιστρέφει `4xx` — αυτά δεν επαναλαμβάνονται
Ένα συμβάν δεν φτάνει ποτέ	Το endpoint δεν είναι εγγεγραμμένο σε αυτόν τον τύπο ή ο διακομιστής έχασε το premium
Διπλά συμβάντα	Αναμενόμενο στις επαναπροσπάθειες — κάντε deduplicate με βάση το `X-TicketWave-Delivery`

Επόμενα Βήματα

Event Reference (Κάθε συμβάν και το payload του)
Example Server (Ένας εκτελέσιμος Express δέκτης)
Log Channels (Τα ίδια συμβάντα, αλλά δημοσιευμένα στο Discord)

Επισκόπηση