Webhookide API

Webhookid teavitavad sinu rakendust reaalajas, kui su tunnistustega midagi juhtub — kui mõni väljastatakse, edastatakse, tühistatakse või vaadatakse. Selle asemel et API-t korduvalt pärida, registreerid sa HTTPS-lõpp-punkti ja badges.ninja saadab sellele iga sündmuse kohta, millele oled tellinud, allkirjastatud POST-päringu.

Kõik haldusotspunktid nõuavad autentimist päise X-Api-Key kaudu. Vt Autentimine. Lõpp-punktide loomine või kustutamine nõuab write-ulatusega võtit; loendamine nõuab read-ulatust. Vt API-võtmed.

Lõpp-punkti registreerimine

POST /webhooks

Parameetrid

Parameeter	Tüüp	Nõutav	Kirjeldus
url	string	Jah	Sinu HTTPS-lõpp-punkt. Peab algama https://-ga.
events	string[]	Ei	Sündmuste tüübid, millele tellida. Jäta ära või anna ["*"], et saada kõik sündmused.

Näide

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"]
  }'

Vastus

201 Created. Allkirjastamise saladus tagastatakse ainult üks kord — salvesta see kohe; seda ei saa uuesti kätte saada.

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

Lõpp-punktide loendamine

GET /webhooks

Tagastab sinu registreeritud lõpp-punktid. Allkirjastamise saladusi ei lisata kunagi.

{
  "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
    }
  ]
}

Lõpp-punkti kustutamine

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"

Edastamine sellele lõpp-punktile peatub kohe.

Sündmuste tüübid

Sündmus	Käivitub, kui…
credential.issued	Tunnistus väljastatakse saajale.
credential.delivered	Tunnistuse teavituse e-kiri saadetakse saajale (üksik või hulgi).
credential.revoked	Tunnistus tühistatakse.
credential.viewed	Saaja avalikku tunnistuse lehte vaadatakse esimest korda.

Edastamise andmed (payload)

Iga edastus on POST sellise kujuga JSON-kehaga:

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

Väli	Kirjeldus
id	Unikaalne edastuse id (kasuta seda duplikaatide eemaldamiseks).
type	Sündmuse tüüp.
createdAt	Sündmuse ajatempel (epohh millisekundites).
data	Sündmusepõhine andmesisu (vt allpool).

data sündmuse tüübi järgi

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" }
}

Päringu päised

Iga edastus kannab neid päiseid:

Päis	Kirjeldus
X-Bws-Event	Sündmuse tüüp (sama mis type kehas).
X-Bws-Delivery	Edastuse id (sama mis id kehas).
X-Bws-Signature	sha256=, millele järgneb toore päringukeha HMAC-SHA256, mille võtmeks on sinu lõpp-punkti saladus.
User-Agent	badges.ninja-webhooks/1

Allkirjade kontrollimine

Kontrolli alati allkirja, enne kui edastust usaldad. Arvuta toore päringukeha HMAC-SHA256, kasutades oma lõpp-punkti allkirjastamise saladust, ja võrdle seda (konstantse ajaga) päisega 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);
}

Kasuta täpselt neid baite, mille said — JSON-i esmalt parsimine ja uuesti serialiseerimine muudab baite ja rikub allkirja.

Kordused ja töökindlus

• Edastus loetakse edukaks, kui sinu lõpp-punkt vastab 2xx-staatusega.
• Ebaõnnestunud edastusi korratakse mõned korrad. Lõpp-punktid, mis pidevalt ebaõnnestuvad, koguvad failureCount-i; pärast 20 järjestikust ebaõnnestumist keelatakse lõpp-punkt automaatselt (active: false) ja see lakkab edastusi vastu võtmast, kuni sa selle parandad ja registreerid uue lõpp-punkti.
• Edastused võivad saabuda rohkem kui üks kord. Kasuta X-Bws-Delivery id-d (või keha id-d), et muuta oma töötleja idempotentseks.
• Vasta kiiresti (umbes 10 sekundi jooksul). Tee rasket tööd asünkroonselt pärast kinnitamist.

Webhookide haldamine töölaual

Lõpp-punkte saad hallata ka ilma API-ta — ava töölaua küljemenüüst Webhookid, et lisada, loendada ja kustutada lõpp-punkte ning valida, milliseid sündmusi igaüks neist saab.