Webhooks API

Τα webhooks ειδοποιούν την εφαρμογή σας σε πραγματικό χρόνο όταν συμβαίνουν πράγματα στα διαπιστευτήριά σας — όταν κάποιο εκδίδεται, παραδίδεται, ανακαλείται ή προβάλλεται. Αντί να ρωτάτε επανειλημμένα το API, καταχωρείτε ένα HTTPS endpoint και το badges.ninja του στέλνει ένα υπογεγραμμένο POST για κάθε συμβάν στο οποίο έχετε εγγραφεί.

Όλα τα endpoints διαχείρισης απαιτούν πιστοποίηση μέσω της κεφαλίδας X-Api-Key. Δείτε Πιστοποίηση. Η δημιουργία ή διαγραφή endpoints απαιτεί κλειδί με εμβέλεια write· η προβολή απαιτεί read. Δείτε Κλειδιά API.

Καταχώρηση ενός Endpoint

POST /webhooks

Παράμετροι

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
url	string	Ναι	Το HTTPS endpoint σας. Πρέπει να ξεκινά με https://.
events	string[]	Όχι	Τύποι συμβάντων για εγγραφή. Παραλείψτε το ή περάστε ["*"] για να λαμβάνετε όλα τα συμβάντα.

Παράδειγμα

curl -X POST https://api.badges.ninja/webhooks \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/badges",
    "events": ["credential.issued", "credential.delivered"]
  }'

Απόκριση

201 Created. Το μυστικό υπογραφής επιστρέφεται μόνο μία φορά — αποθηκεύστε το τώρα· δεν μπορείτε να το ανακτήσετε ξανά.

{
  "id": "e4b19ff5-063d-4799-bd75-d03641be624f",
  "url": "https://example.com/hooks/badges",
  "events": ["credential.issued", "credential.delivered"],
  "secret": "2be6d335682c1658242fde3a523fd8a2493bab8c"
}

Λίστα Endpoints

GET /webhooks

Επιστρέφει τα καταχωρημένα σας endpoints. Τα μυστικά υπογραφής δεν περιλαμβάνονται ποτέ.

{
  "webhooks": [
    {
      "id": "e4b19ff5-063d-4799-bd75-d03641be624f",
      "url": "https://example.com/hooks/badges",
      "events": ["credential.issued", "credential.delivered"],
      "active": true,
      "failureCount": 0,
      "createdAt": 1787685415083,
      "lastStatus": 200,
      "lastDeliveryAt": 1787685480777
    }
  ]
}

Διαγραφή ενός Endpoint

DELETE /webhooks/{id}

curl -X DELETE https://api.badges.ninja/webhooks/e4b19ff5-063d-4799-bd75-d03641be624f \
  -H "X-Api-Key: bws_your_api_key_here"

Οι παραδόσεις στο endpoint σταματούν αμέσως.

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

Συμβάν	Ενεργοποιείται όταν…
credential.issued	Ένα διαπιστευτήριο εκδίδεται σε έναν παραλήπτη.
credential.delivered	Το email ειδοποίησης ενός διαπιστευτηρίου αποστέλλεται στον παραλήπτη (μεμονωμένα ή μαζικά).
credential.revoked	Ένα διαπιστευτήριο ανακαλείται.
credential.viewed	Η δημόσια σελίδα διαπιστευτηρίου ενός παραλήπτη προβάλλεται για πρώτη φορά.

Ωφέλιμο Φορτίο Παράδοσης

Κάθε παράδοση είναι ένα POST με σώμα JSON αυτής της μορφής:

{
  "id": "b1c2d3e4-...",
  "type": "credential.issued",
  "createdAt": 1787685415083,
  "data": { }
}

Πεδίο	Περιγραφή
id	Μοναδικό αναγνωριστικό παράδοσης (χρησιμοποιήστε το για απαλοιφή διπλοτύπων).
type	Ο τύπος του συμβάντος.
createdAt	Χρονοσφραγίδα συμβάντος (χιλιοστά του δευτερολέπτου epoch).
data	Ωφέλιμο φορτίο ειδικό ανά συμβάν (δείτε παρακάτω).

data ανά τύπο συμβάντος

credential.issued

{
  "awardId": "https://api.badges.ninja/certify-badge/award/<guid>",
  "badgeId": "https://api.badges.ninja/certify-badge/badge/<guid>",
  "badgeName": "Advanced Certification",
  "recipient": { "email": "jane@example.com", "name": "Jane Doe" },
  "issuedOn": "2026-08-25",
  "expires": null
}

credential.delivered

{
  "awardId": "https://api.badges.ninja/certify-badge/award/<guid>",
  "recipient": { "email": "jane@example.com", "name": "Jane Doe" },
  "badgeName": "Advanced Certification"
}

credential.revoked

{ "awardId": "https://api.badges.ninja/certify-badge/award/<guid>", "reason": "Issued in error" }

credential.viewed

{
  "awardId": "https://api.badges.ninja/certify-badge/award/<guid>",
  "recipient": { "email": "jane@example.com", "name": "Jane Doe" }
}

Κεφαλίδες Αιτήματος

Κάθε παράδοση φέρει αυτές τις κεφαλίδες:

Κεφαλίδα	Περιγραφή
X-Bws-Event	Ο τύπος του συμβάντος (ίδιος με το type στο σώμα).
X-Bws-Delivery	Το αναγνωριστικό παράδοσης (ίδιο με το id στο σώμα).
X-Bws-Signature	sha256= ακολουθούμενο από το HMAC-SHA256 του ακατέργαστου σώματος του αιτήματος, με κλειδί το μυστικό του endpoint σας.
User-Agent	badges.ninja-webhooks/1

Επαλήθευση Υπογραφών

Πάντα να επαληθεύετε την υπογραφή πριν εμπιστευτείτε μια παράδοση. Υπολογίστε το HMAC-SHA256 του ακατέργαστου σώματος του αιτήματος χρησιμοποιώντας το μυστικό υπογραφής του endpoint σας και συγκρίνετέ το (σε σταθερό χρόνο) με την κεφαλίδα X-Bws-Signature.

import crypto from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Χρησιμοποιήστε τα ακριβή bytes που λάβατε — η ανάλυση και επανασειριοποίηση του JSON πρώτα θα αλλάξει τα bytes και θα χαλάσει την υπογραφή.

Επαναλήψεις & Αξιοπιστία

• Μια παράδοση θεωρείται επιτυχής όταν το endpoint σας αποκρίνεται με κατάσταση 2xx.
• Οι αποτυχημένες παραδόσεις επαναλαμβάνονται λίγες φορές. Τα endpoints που εξακολουθούν να αποτυγχάνουν συσσωρεύουν έναν failureCount· μετά από 20 διαδοχικές αποτυχίες ένα endpoint απενεργοποιείται αυτόματα (active: false) και σταματά να λαμβάνει παραδόσεις μέχρι να το διορθώσετε και να καταχωρήσετε ένα νέο endpoint.
• Οι παραδόσεις μπορεί να φτάσουν περισσότερες από μία φορές. Χρησιμοποιήστε το αναγνωριστικό X-Bws-Delivery (ή το id του σώματος) για να κάνετε τον χειριστή σας ιδεμποτεντικό.
• Αποκριθείτε γρήγορα (εντός ~10 δευτερολέπτων). Κάντε τη βαριά εργασία ασύγχρονα μετά την επιβεβαίωση.

Διαχείριση Webhooks στον Πίνακα Ελέγχου

Μπορείτε επίσης να διαχειρίζεστε τα endpoints χωρίς το API — ανοίξτε τα Webhooks στην πλαϊνή γραμμή του πίνακα ελέγχου για να προσθέσετε, να προβάλετε και να διαγράψετε endpoints και να επιλέξετε ποια συμβάντα λαμβάνει το καθένα.