Webhooks API

Webhooki v realnem času obvestijo vašo aplikacijo, ko se z vašimi poverilnicami kaj zgodi — ko je katera izdana, dostavljena, preklicana ali ogledana. Namesto da API poizvedujete, registrirate končno točko HTTPS in badges.ninja ji za vsak dogodek, na katerega ste naročeni, pošlje podpisan POST.

Vse upravljalske končne točke zahtevajo avtentikacijo prek glave X-Api-Key. Glejte Avtentikacija. Ustvarjanje ali brisanje končnih točk zahteva ključ z obsegom write; izpisovanje zahteva read. Glejte API ključi.

Registracija končne točke

POST /webhooks

Parametri

Parameter	Tip	Obvezno	Opis
url	string	Da	Vaša končna točka HTTPS. Mora se začeti z https://.
events	string[]	Ne	Tipi dogodkov, na katere se naročate. Izpustite ali podajte ["*"], da prejemate vse dogodke.

Primer

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

Odziv

201 Created. Podpisna skrivnost se vrne samo enkrat — shranite jo zdaj; kasneje je ne morete več pridobiti.

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

Izpis končnih točk

GET /webhooks

Vrne vaše registrirane končne točke. Podpisne skrivnosti niso nikoli vključene.

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

Brisanje končne točke

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"

Dostave na to končno točko se takoj ustavijo.

Tipi dogodkov

Dogodek	Sproži se, ko …
credential.issued	Je poverilnica izdana prejemniku.
credential.delivered	Je obvestilo o poverilnici po e-pošti poslano prejemniku (posamično ali množično).
credential.revoked	Je poverilnica preklicana.
credential.viewed	Je javna stran poverilnice prejemnika ogledana prvič.

Vsebina dostave

Vsaka dostava je POST s telesom JSON te oblike:

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

Polje	Opis
id	Enolični id dostave (uporabite ga za odpravljanje podvajanja).
type	Tip dogodka.
createdAt	Časovni žig dogodka (milisekunde od epohe).
data	Vsebina, specifična za dogodek (glejte spodaj).

data po tipu dogodka

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

Glave zahteve

Vsaka dostava nosi te glave:

Glava	Opis
X-Bws-Event	Tip dogodka (enak kot type v telesu).
X-Bws-Delivery	Id dostave (enak kot id v telesu).
X-Bws-Signature	sha256=, ki mu sledi HMAC-SHA256 surovega telesa zahteve, s ključem vaše podpisne skrivnosti končne točke.
User-Agent	badges.ninja-webhooks/1

Preverjanje podpisov

Pred zaupanjem dostavi vedno preverite podpis. Izračunajte HMAC-SHA256 surovega telesa zahteve z uporabo podpisne skrivnosti vaše končne točke in ga (v konstantnem času) primerjajte z glavo 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);
}

Uporabite natanko tiste bajte, ki ste jih prejeli — če JSON najprej razčlenite in znova serializirate, se bajti spremenijo in podpis se poruši.

Ponovni poskusi in zanesljivost

• Dostava velja za uspešno, ko vaša končna točka odgovori s statusom 2xx.
• Neuspešne dostave se ponovijo nekajkrat. Končne točke, ki še naprej odpovedujejo, kopičijo failureCount; po 20 zaporednih neuspehih se končna točka samodejno onemogoči (active: false) in preneha prejemati dostave, dokler je ne popravite in registrirate nove končne točke.
• Dostave lahko prispejo večkrat. Uporabite id X-Bws-Delivery (ali id iz telesa), da naredite svoj obravnavalnik idempotenten.
• Odgovorite hitro (v približno 10 sekundah). Zahtevnejše delo opravite asinhrono po potrditvi.

Upravljanje webhookov v nadzorni plošči

Končne točke lahko upravljate tudi brez API — v stranski vrstici nadzorne plošče odprite Webhooks, da dodate, izpišete in izbrišete končne točke ter izberete, katere dogodke vsaka prejema.