Webhooks

Λαμβάνετε τα συμβάντα των συνεδριών σας στο backend σας: κάθε παράδοση υπογράφεται με HMAC-SHA256, επαναλαμβάνεται με εκθετικά αυξανόμενη αναμονή και φέρει μοναδικό αναγνωριστικό, ώστε ο δέκτης σας να μπορεί να αγνοεί τα διπλότυπα.

Πότε να χρησιμοποιήσετε webhooks

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

Κατάλογος συμβάντων

Σερβίρεται από το API στο /public/v1/limits — αυτή η σελίδα δεν κρατά αντίγραφο.

Κεφαλίδες σε κάθε παράδοση

X-Votinova-EventΟ τύπος του συμβάντος, ακριβώς όπως εμφανίζεται στον κατάλογο.
X-Votinova-Delivery-IdΜοναδικό ανά παράδοση — το κλειδί σας για την απαλοιφή διπλότυπων.
X-Votinova-TimestampΔευτερόλεπτα epoch· αποτελεί μέρος όσων υπογράφονται, οπότε μια επαναλαμβανόμενη παράδοση δεν μπορεί να ξαναχρονολογηθεί.
X-Votinova-SignatureHMAC-SHA256 σε δεκαεξαδική μορφή, χωρίς πρόθεμα.

Το σώμα είναι συμπαγές JSON με το συμβάν και κάθε αναγνωριστικό που εμπλέκεται — αυτή είναι, byte προς byte, η υπογεγραμμένη δοκιμαστική παράδοση:

{"event":"session.ended","session_id":"68b2e3d4c5f607182930a5bc"}

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

Κάθε παράδοση υπογράφεται με HMAC-SHA256 πάνω στη χρονοσήμανση, μια τελεία και το σώμα, με κλειδί το μυστικό του σημείου πρόσβασης. Συγκρίνετε το αποτέλεσμα με την κεφαλίδα X-Votinova-Signature.

Υπογράψτε το ΑΚΑΤΕΡΓΑΣΤΟ σώμα. Η ανάλυση και η εκ νέου σειριοποίησή του αλλάζουν τα κενά και η υπογραφή παύει να ταιριάζει.
Συγκρίνετε σε σταθερό χρόνο, όχι με ==.

Επαληθευμένο σε πραγματική παράδοση

const crypto = require("node:crypto");

function verify(headers, rawBody, secret) {
  const timestamp = headers["x-votinova-timestamp"];
  const signature = headers["x-votinova-signature"];
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

secret     whsec_3f8a1c92d4e5b6a7
timestamp  1785321600
body       {"event":"session.ended","session_id":"68b2e3d4c5f607182930a5bc"}

HMAC-SHA256(secret, timestamp + "." + body)
= 10a86171bd92f5fcf8c28b873978e0214302cc2291c54cc016d18347f3ee7c38

Επαναλήψεις

Παραδόσεις webhook: έως 8 προσπάθειες, με αυξανόμενες αναμονές 21, 45, 95, 171, 369, 732, 1480 δευτερολέπτων. Μόλις εξαντληθούν, η παράδοση χαρακτηρίζεται οριστικά αποτυχημένη και μπορεί να επαναληφθεί με το χέρι.

Ιδεμποτικότητα

Χρησιμοποιήστε το X-Votinova-Delivery-Id ως κλειδί απαλοιφής διπλότυπων: μια παράδοση μπορεί να φτάσει περισσότερες από μία φορές και το αποτέλεσμά της πρέπει να εφαρμοστεί μόνο μία φορά.

X-Votinova-Delivery-Id

Καλές πρακτικές

Απαντήστε 200 μόλις η παράδοση είναι ασφαλής και επεξεργαστείτε τη στη δική σας ουρά — ένας αργός δέκτης συσσωρεύει επαναλήψεις.
ΠΑΝΤΑ επαληθεύετε την υπογραφή πριν αναλύσετε το σώμα: χωρίς αυτήν, όποιος ξέρει τη διεύθυνσή σας μπορεί να επινοήσει συμβάντα.
Απαλείψτε τα διπλότυπα με βάση το X-Votinova-Delivery-Id: το «τουλάχιστον μία φορά» σημαίνει ότι η ίδια παράδοση μπορεί να σας καλέσει δύο φορές.
Μετά από 10 διαδοχικές αποτυχίες το σημείο πρόσβασης τίθεται σε παύση μόνο του· επανενεργοποιήστε το από τον πίνακα ή μέσω API μόλις ο δέκτης σας επανέλθει.