Επισκόπηση των webhooks

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

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

Το συμβάν

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

Το data περιέχει μόνο ό,τι θα μπορούσε να δει μέσω του API οποιοσδήποτε αναγνώστης του αντικειμένου. Δεν περιέχει ποτέ λίστες πρόσβασης, τα δικαιώματα άλλων ανθρώπων ή κρυφά πεδία. Οι αιτίες στα συμβάντα είναι σύντομοι ουδέτεροι κωδικοί, όπως no_hits, restricted ή index_failed.

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

Τα συμβάντα καλύπτουν τους εξής τομείς:

Η πλήρης λίστα, με το σχήμα και ένα παράδειγμα κάθε συμβάντος, βρίσκεται στον κατάλογο συμβάντων της αναφοράς API. Το GET /v1/webhooks/catalog επιστρέφει τους τύπους που είναι διαθέσιμοι στην εγκατάστασή σας.

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

Ποιος λαμβάνει τι

Ένα webhook λαμβάνει ένα συμβάν μόνο αν το αντικείμενο του συμβάντος είναι ορατό στο webhook, με τον ίδιο τρόπο όπως σε ένα κλειδί API: ανάλογα με τον ρόλο του, το προφίλ δεδομένων του και τις συλλογές του. Ένα webhook περιορισμένο στη συλλογή support δεν λαμβάνει ποτέ συμβάντα για κάρτες στη finance. Τα συμβάντα για άτομα, κλειδιά, πηγές, εισαγωγές, εργασίες, εξαγωγές, χρεώσεις, εφαρμογές και για τα ίδια τα webhooks πηγαίνουν μόνο σε webhooks με τον ρόλο admin.

Μέσα σε αυτά τα πλαίσια, κάθε webhook επιλέγει τα συμβάντα του:

• κατά τύπο, με μάσκες: card.* για κάθε συμβάν κάρτας, * για κάθε συμβάν·
• κατά συλλογή και κατά ετικέτα, για τα συμβάντα καρτών.

Η μορφή σώματος ενός webhook είναι full (το συμβάν με data, η προεπιλογή) ή thin (το συμβάν χωρίς data: ο παραλήπτης σας διαβάζει το αντικείμενο μέσω του API με το δικό του κλειδί και βλέπει πάντα την τρέχουσα κατάστασή του).

Η παράδοση με λίγα λόγια

• Ένα POST μέσω HTTPS με το συμβάν ως JSON, υπογεγραμμένο με το μυστικό του webhook σε δύο μορφές: Standard Webhooks (webhook-signature) και την παλαιότερη X-KB-Signature.
• Οποιαδήποτε απάντηση 2xx μέσα σε 10 δευτερόλεπτα είναι επιτυχία.
• Μια αποτυχία επαναλαμβάνεται για σχεδόν τρεις ημέρες με αυξανόμενες παύσεις. Το Retry-After σε μια απάντηση 429 ή 503 τηρείται· το 410 απενεργοποιεί το webhook· 10 διαδοχικές αποτυχίες το θέτουν σε παύση μέχρι να συνεχιστεί.
• Οι παραδόσεις προς ένα webhook στέλνονται αυστηρά με τη σειρά. Ένα αργό webhook δεν καθυστερεί τα άλλα webhooks.
• Το ίδιο συμβάν μπορεί να φτάσει περισσότερες από μία φορές: απορρίπτετε τα διπλότυπα με βάση το webhook-id.

Ο οδηγός Λήψη webhooks περιγράφει βήμα προς βήμα έναν πλήρη παραλήπτη, με ελέγχους υπογραφής σε Node.js, Python και Go.

Διαχείριση webhooks

Η διαχείριση των webhooks απαιτεί ένα κλειδί με τον ρόλο admin και την εμβέλεια webhooks:manage ή έναν διαχειριστή στο περιβάλλον διαχείρισης. Ένας οργανισμός μπορεί να έχει έως 20 webhooks. Τα webhooks είναι μέρος του πακέτου του οργανισμού· χωρίς αυτά, αυτά τα τελικά σημεία απαντούν 403 με τον κωδικό webhooks.feature_disabled.