Webhooks API

Webhooky upozorňují vaši aplikaci v reálném čase na události týkající se vašich přihlašovacích údajů — když jsou vydány, doručeny, odvolány nebo zobrazeny. Namísto dotazování API zaregistrujete HTTPS endpoint a badges.ninja na něj pošle podepsaný POST pro každou událost, kterou odebíráte.

Všechny správní endpointy vyžadují autentizaci pomocí hlavičky X-Api-Key. Viz Autentizace. Vytváření nebo mazání endpointů vyžaduje klíč s oprávněním write; výpis vyžaduje read. Viz Klíče API.

Registrace endpointu

POST /webhooks

Parametry

Parametr	Typ	Povinný	Popis
url	string	Ano	Váš HTTPS endpoint. Musí začínat na https://.
events	string[]	Ne	Typy událostí k odběru. Vynechte nebo předejte ["*"] pro příjem všech událostí.

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

Odpověď

201 Created. Podpisové tajemství se vrací pouze jednou — uložte si jej nyní; znovu jej získat nelze.

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

Výpis endpointů

GET /webhooks

Vrací vaše registrované endpointy. Podpisová tajemství nejsou nikdy zahrnuta.

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

Smazání endpointu

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čování na tento endpoint se okamžitě zastaví.

Typy událostí

Událost	Spustí se, když…
credential.issued	Přihlašovací údaje jsou vydány příjemci.
credential.delivered	E-mail s upozorněním na přihlašovací údaje je odeslán příjemci (jednotlivě nebo hromadně).
credential.revoked	Přihlašovací údaje jsou odvolány.
credential.viewed	Veřejná stránka přihlašovacích údajů příjemce je zobrazena poprvé.

Datová část doručení

Každé doručení je POST s tělem JSON tohoto tvaru:

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

Pole	Popis
id	Jedinečné ID doručení (použijte jej k deduplikaci).
type	Typ události.
createdAt	Časové razítko události (milisekundy epochy).
data	Datová část specifická pro událost (viz níže).

data podle typu události

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žadavku

Každé doručení nese tyto hlavičky:

Hlavička	Popis
X-Bws-Event	Typ události (stejný jako type v těle).
X-Bws-Delivery	ID doručení (stejné jako id v těle).
X-Bws-Signature	sha256= následované HMAC-SHA256 surového těla požadavku, s klíčem, kterým je tajemství vašeho endpointu.
User-Agent	badges.ninja-webhooks/1

Ověřování podpisů

Před důvěrou v doručení vždy ověřte podpis. Vypočítejte HMAC-SHA256 surového těla požadavku pomocí podpisového tajemství vašeho endpointu a porovnejte jej (v konstantním č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žijte přesně ty bajty, které jste obdrželi — parsování a opětovná serializace JSON změní bajty a poruší podpis.

Opakování a spolehlivost

• Doručení je považováno za úspěšné, když váš endpoint odpoví stavem 2xx.
• Neúspěšná doručení se několikrát opakují. Endpointy, které nadále selhávají, hromadí failureCount; po 20 po sobě jdoucích selháních je endpoint automaticky deaktivován (active: false) a přestane přijímat doručení, dokud problém neopravíte a nezaregistrujete nový endpoint.
• Doručení mohou dorazit více než jednou. Použijte ID X-Bws-Delivery (nebo id z těla), aby byl váš handler idempotentní.
• Odpovídejte rychle (do ~10 sekund). Náročnou práci provádějte asynchronně po potvrzení.

Správa webhooků v panelu

Endpointy můžete spravovat i bez API — otevřete Webhooks v postranním panelu, kde můžete přidávat, vypisovat a mazat endpointy a vybírat, které události každý z nich přijímá.