Webhooks API

Webhooky upozorňujú vašu aplikáciu v reálnom čase, keď sa niečo stane s vašimi poverovacími listinami — keď je niektorá vydaná, doručená, odvolaná alebo zobrazená. Namiesto opakovaného dopytovania API zaregistrujete HTTPS koncový bod a badges.ninja mu pošle podpísaný POST pri každej udalosti, na ktorú sa prihlásite.

Všetky správcovské koncové body vyžadujú autentifikáciu prostredníctvom hlavičky X-Api-Key. Pozri Autentifikácia. Vytváranie alebo mazanie koncových bodov vyžaduje kľúč s rozsahom write; výpis vyžaduje read. Pozri API kľúče.

Registrácia koncového bodu

POST /webhooks

Parametre

Parameter	Typ	Povinný	Popis
url	string	Áno	Váš HTTPS koncový bod. Musí začínať na https://.
events	string[]	Nie	Typy udalostí, na ktoré sa chcete prihlásiť. Vynechajte alebo zadajte ["*"], ak chcete prijímať všetky udalosti.

Príklad

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

Odpoveď

201 Created. Podpisové tajomstvo sa vráti iba raz — uložte si ho teraz; už ho nebudete môcť znova získať.

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

Výpis koncových bodov

GET /webhooks

Vráti vaše zaregistrované koncové body. Podpisové tajomstvá nie sú nikdy zahrnuté.

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

Odstránenie koncového bodu

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"

Doručovanie na koncový bod sa okamžite zastaví.

Typy udalostí

Udalosť	Spustí sa, keď…
credential.issued	Poverovacia listina je vydaná príjemcovi.
credential.delivered	E-mail s upozornením na poverovaciu listinu je odoslaný príjemcovi (jednotlivo alebo hromadne).
credential.revoked	Poverovacia listina je odvolaná.
credential.viewed	Verejná stránka poverovacej listiny príjemcu je zobrazená prvýkrát.

Payload doručenia

Každé doručenie je POST s JSON telom tohto tvaru:

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

Pole	Popis
id	Jedinečné id doručenia (použite ho na odstránenie duplikátov).
type	Typ udalosti.
createdAt	Časová značka udalosti (epoch v milisekundách).
data	Payload špecifický pre udalosť (pozri nižšie).

data podľa typu udalosti

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

Hlavičky požiadavky

Každé doručenie nesie tieto hlavičky:

Hlavička	Popis
X-Bws-Event	Typ udalosti (rovnaký ako type v tele).
X-Bws-Delivery	Id doručenia (rovnaké ako id v tele).
X-Bws-Signature	sha256= nasledované HMAC-SHA256 surového tela požiadavky, kľúčovaným tajomstvom vášho koncového bodu.
User-Agent	badges.ninja-webhooks/1

Overovanie podpisov

Pred dôverovaním doručeniu vždy overte podpis. Vypočítajte HMAC-SHA256 zo surového tela požiadavky pomocou podpisového tajomstva vášho koncového bodu a porovnajte ho (v konštantnom čase) s hlavičkou 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);
}

Použite presné bajty, ktoré ste prijali — ak JSON najprv rozparsujete a znova serializujete, zmeníte bajty a podpis prestane platiť.

Opakovania a spoľahlivosť

• Doručenie sa považuje za úspešné, keď váš koncový bod odpovie so stavom 2xx.
• Neúspešné doručenia sa niekoľkokrát zopakujú. Koncové body, ktoré stále zlyhávajú, nazbierajú failureCount; po 20 po sebe idúcich zlyhaniach je koncový bod automaticky deaktivovaný (active: false) a prestane prijímať doručenia, kým ho neopravíte a nezaregistrujete nový koncový bod.
• Doručenia môžu prísť viackrát. Použite id X-Bws-Delivery (alebo id z tela), aby bol váš handler idempotentný.
• Odpovedajte rýchlo (do ~10 sekúnd). Náročnú prácu vykonajte asynchrónne po potvrdení.

Správa webhookov v paneli

Koncové body môžete spravovať aj bez API — otvorte Webhooks v bočnom paneli, kde môžete pridávať, vypisovať a mazať koncové body a vyberať, ktoré udalosti každý z nich prijíma.