Webhooks

Το RolChat παραδίδει συμβάντα στα συστήματά σας ως υπογεγραμμένα αιτήματα HTTP POST. Αυτή η σελίδα περιγράφει τα webhooks των plugins· τα webhooks που στέλνει ένας κανόνας Αυτοματισμού διαφέρουν στις επαναλήψεις, στον χρόνο αναμονής και στην αλλαγή μυστικού, βλ. Webhooks αυτοματισμού. Οι ίδιοι κανόνες ισχύουν και προς την αντίθετη κατεύθυνση, όταν το σύστημά σας, ένα plugin ή ένας πάροχος στέλνει δεδομένα στο RolChat. Επαληθεύστε κάθε παράδοση με την παρακάτω σειρά πριν ενεργήσετε βάσει αυτής.

Πώς μοιάζει μια παράδοση

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: RolChat-Webhook/1.0
X-RolChat-Timestamp: 1713615825
X-RolChat-Signature: sha256=a1b2c3…
X-RolChat-Nonce: nonce_01HKQN9…
X-RolChat-Event-Id: evt_01HKQN9…

{ "id": "evt_01HKQN9…", "type": "conversation.created", "occurred_at": "…", "data": { … } }

Κεφαλίδα	Σημασία
`X-RolChat-Timestamp`	Δευτερόλεπτα Unix κατά την αποστολή. Μέρος του υπογεγραμμένου μηνύματος.
`X-RolChat-Signature`	`sha256=<hex>`. Το πρόθεμα ονομάζει τον αλγόριθμο, ώστε να μπορεί να αλλάξει αργότερα.
`X-RolChat-Nonce`	Ένα ULID μοναδικό για αυτό το αίτημα HTTP. Μια επανάληψη λαμβάνει νέο nonce.
`X-RolChat-Event-Id`	Το αναγνωριστικό του ίδιου του συμβάντος. Σταθερό σε όλες τις επαναλήψεις· χρησιμοποιήστε το για αφαίρεση διπλοτύπων.

Οι εξερχόμενες παραδόσεις πηγαίνουν μόνο σε endpoints HTTPS. Ένα URL HTTP απορρίπτεται κατά τη δημιουργία της συνδρομής.

Η υπογραφή

Το υπογεγραμμένο μήνυμα είναι η χρονοσφραγίδα, μια κυριολεκτική τελεία και το ακατέργαστο σώμα του αιτήματος, byte προς byte:

canonical = "<timestamp>.<body>"
signature = hex( HMAC-SHA256( secret, canonical ) )

Υπογράψτε τα bytes που λάβατε, όχι ένα επανασειριοποιημένο αντίγραφο του αναλυμένου JSON. Αλλαγές σε κενά ή στη σειρά των κλειδιών σπάνε την υπογραφή. Ο SHA-256 είναι ο μόνος αποδεκτός αλγόριθμος.

Τα αιτήματα που στέλνει η ενέργεια HTTP της ενότητας Αυτοματισμός υπογράφονται με δύο κεφαλίδες. Η X-RolChat-Signature είναι sha256= συν το HMAC-SHA256 μόνο του σώματος. Η X-RolChat-Signature-V2 είναι το HMAC-SHA256 του <timestamp>.<body>, το σχήμα που περιγράφεται παραπάνω, με την X-RolChat-Timestamp ως χρονική σήμανση. Επαληθεύετε την κεφαλίδα V2· η κεφαλίδα μόνο για το σώμα δεν προστατεύει από επανάληψη αιτήματος. Αυτά τα αιτήματα δεν φέρουν X-RolChat-Nonce ούτε X-RolChat-Event-Id· όλες οι προσπάθειες μιας παράδοσης φέρουν την ίδια X-RolChat-Delivery-Id και τον δικό τους αριθμό στην X-RolChat-Attempt, οπότε παραλείψτε τον έλεγχο nonce και αποδιπλασιάστε με βάση την X-RolChat-Delivery-Id. Τα παραδείγματα επαλήθευσης διαβάζουν την X-RolChat-Signature: για αιτήματα αυτοματισμού διαβάστε στη θέση της την X-RolChat-Signature-V2.

Επαλήθευση μιας παράδοσης

Κάντε αυτούς τους πέντε ελέγχους με τη σειρά. Παραδείγματα σε Python, Node.js, Go, Ruby και PHP βρίσκονται στη σελίδα παραδείγματα επαλήθευσης.

Εγκυρότητα χρόνου. Απορρίψτε αν |now − X-RolChat-Timestamp| > 300 δευτερόλεπτα (400). Τα πέντε λεπτά ανέχονται απόκλιση ρολογιού και καθιστούν ένα υποκλαπέν αίτημα άχρηστο μετά από αυτό το διάστημα. Κρατήστε τον διακομιστή σας συγχρονισμένο με NTP.
Υπογραφή. Υπολογίστε την αναμενόμενη τιμή και συγκρίνετε με σύγκριση σταθερού χρόνου (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Απορρίψτε με 401 σε αναντιστοιχία. Μια απλή σύγκριση συμβολοσειρών διαρρέει πληροφορία χρονισμού και δεν είναι αποδεκτή.
Nonce. Αποθηκεύστε το X-RolChat-Nonce με TTL 10 λεπτών χρησιμοποιώντας ατομικό set-if-absent (SET NX EX 600). Αν υπάρχει ήδη, απορρίψτε με 409: το αίτημα είναι επανάληψη. Αν η αποθήκη nonce δεν είναι διαθέσιμη, αποτύχετε κλειστά με 503 ώστε το RolChat να επαναλάβει· μην καταλήγετε ποτέ σε «αποδοχή».
Αναλύστε το σώμα μόνο τώρα.
Αφαιρέστε διπλότυπα με βάση το αναγνωριστικό συμβάντος. Οι επαναλήψεις φέρουν νέο nonce αλλά το ίδιο X-RolChat-Event-Id. Αν έχετε επεξεργαστεί αυτό το αναγνωριστικό τις τελευταίες επτά ημέρες, απαντήστε 200 χωρίς νέα επεξεργασία.

Απαντήστε 2xx μόλις η παράδοση γίνει με ασφάλεια αποδεκτή· κάντε την εργασία ασύγχρονα. Το RolChat περιμένει 15 δευτερόλεπτα για απόκριση.

Μυστικά

Ένα μυστικό webhook αποτελείται από 64 τυχαία bytes, κωδικοποιημένα σε base64url (περίπου 86 χαρακτήρες). Παράγεται όταν δημιουργείται η συνδρομή ή το plugin και εμφανίζεται μία φορά.
Αποθηκεύστε το στο δικό σας vault ή περιβάλλον· το RolChat κρατά μόνο κρυπτογραφημένο αντίγραφο.
Συνιστάται εναλλαγή μετά από 90 ημέρες· το προϊόν εμφανίζει υπενθύμιση αλλά δεν απενεργοποιεί ποτέ μια συνδρομή λόγω μη εναλλαγής.
Η εναλλαγή χρησιμοποιεί παράθυρο επικάλυψης: μετά το POST /api/v1/plugins/{id}/webhook-secret/rotate και το παλιό και το νέο μυστικό επαληθεύουν για επτά ημέρες, οι νέες παραδόσεις υπογράφονται με το νέο και το παλιό διαγράφεται μετά το παράθυρο. Τίποτα δεν σπάει τη στιγμή της εναλλαγής.
Αν ένα μυστικό διαρρεύσει, το POST /api/v1/plugins/{id}/webhook-secret/revoke το ακυρώνει αμέσως, εκδίδει νέο, στέλνει email στους admins του λογαριασμού και γράφει καταχώριση στο αρχείο ελέγχου.

Επαναλήψεις και dead letters

Μια απόκριση εκτός 2xx ή μια αποτυχία δικτύου προγραμματίζει επανάληψη:

Προσπάθεια	Καθυστέρηση μετά την προηγούμενη
1	αμέσως
2	15 δευτερόλεπτα
3	1 λεπτό
4	5 λεπτά
5	30 λεπτά
6	2 ώρες
7	8 ώρες
8	24 ώρες

Τα 408, 429, 5xx και τα σφάλματα δικτύου επαναλαμβάνονται. Τα 400, 401, 403, 404 και 410 όχι: η παράδοση πηγαίνει κατευθείαν στην ουρά dead letters, επειδή η επανάληψη μιας απορριφθείσας υπογραφής ή ενός ανύπαρκτου endpoint δεν μπορεί να βοηθήσει. Μετά από οκτώ αποτυχημένες προσπάθειες η παράδοση πηγαίνει επίσης στα dead letters.

Τα dead letters διατηρούνται για 30 ημέρες και είναι ορατά στις Ρυθμίσεις → Plugins → {plugin} → Αρχείο webhooks → DLQ, όπου ένας admin μπορεί να επαναλάβει την αποστολή τους (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Όρια

Εξερχόμενο σώμα: 1 MB από προεπιλογή (ρυθμιζόμενο ανά plugin). Εισερχόμενο σώμα προς το RolChat: 5 MB. Μεγαλύτερο δίνει 413.
Ένα plugin μπορεί να δηλώσει allowed_source_ips· το RolChat εφαρμόζει αυτή τη λίστα επιτρεπόμενων πριν από την επαλήθευση.
Μπορείτε να ελέγχετε τον user agent RolChat-Webhook/1.0 ως επιπλέον έλεγχο λογικής. Δεν αποτελεί μέτρο ασφαλείας.

Εισερχόμενα webhooks προς το RolChat

Οι πάροχοι στέλνουν στο RolChat στη διεύθυνση /api/v1/webhooks/{category}/{adapter} χρησιμοποιώντας τα δικά τους σχήματα υπογραφής (Twilio, Telnyx, Bandwidth, Meta για WhatsApp, Stripe). Κάθε προσαρμογέας επαληθεύει την υπογραφή του παρόχου του, κανονικοποιεί το payload και το αναδημοσιεύει στον εσωτερικό δίαυλο συμβάντων με υπογραφή RolChat. Το δικό σας σύστημα μπορεί να στέλνει στο RolChat με τις ίδιες κεφαλίδες X-RolChat-* που περιγράφονται παραπάνω, υπογεγραμμένες με το μυστικό του plugin στο οποίο ανήκει το endpoint.

Webhooks αυτοματισμού

Η ενέργεια Αποστολή αιτήματος HTTP της ενότητας Αυτοματισμός έχει δικούς της κανόνες παράδοσης:

Ένα μυστικό ανά λογαριασμό. Εμφανίστε ή αλλάξτε το στην οθόνη Αυτοματισμού (Owner και Admin). Η αλλαγή ισχύει αμέσως: δεν υπάρχει παράθυρο επικάλυψης, το παλιό μυστικό παύει να επαληθεύεται άμεσα, γι’ αυτό ενημερώστε πρώτα τον δέκτη σας ή αποδεχτείτε ένα σύντομο κενό.
Χρόνος αναμονής: το RolChat περιμένει 10 δευτερόλεπτα για απάντηση.
Επαναλήψεις: έως 6 προσπάθειες συνολικά. Η παύση πριν από την προσπάθεια 2 είναι 30 δευτερόλεπτα, έπειτα περίπου 2 λεπτά, 8 λεπτά, 32 λεπτά και 2 ώρες 8 λεπτά, με απόκλιση έως 20 % η καθεμία. Μία παύση δεν ξεπερνά ποτέ τις 6 ώρες.
Τι επαναλαμβάνεται: σφάλματα δικτύου, λήξεις χρόνου, 5xx, 408, 425 και 429. Άλλες απαντήσεις 4xx, μια αποκλεισμένη διεύθυνση ή ένα υπερβολικά μεγάλο σώμα δεν επαναλαμβάνονται: η παράδοση πηγαίνει κατευθείαν στην ουρά dead-letter, όπως και μετά την τελευταία αποτυχημένη προσπάθεια.
Κεφαλίδες: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Δοκιμή του δέκτη σας

Το POST /api/v1/webhooks/test-signature στέλνει ένα συνθετικό υπογεγραμμένο συμβάν στο endpoint του plugin που καλεί, ώστε να επαληθεύσετε την υλοποίησή σας από άκρη σε άκρη πριν φτάσει πραγματική κίνηση.

Συνηθισμένα λάθη

Επαλήθευση έναντι του αναλυμένου και επανακωδικοποιημένου JSON αντί για τα ακατέργαστα bytes.
Χρήση του == για σύγκριση υπογραφών.
Αφαίρεση διπλοτύπων με βάση το nonce (κάθε επανάληψη έχει νέο) αντί για το αναγνωριστικό συμβάντος.
Ρολόι με απόκλιση μεγαλύτερη από πέντε λεπτά.
Εκτέλεση αργής εργασίας πριν από την απάντηση, με αποτέλεσμα λήξη χρόνου στα 15 δευτερόλεπτα και εκ νέου λήψη του ίδιου συμβάντος.