Webhook API

A webhookok valós időben értesítik az alkalmazásodat, amikor valami történik a hitelesítő adataiddal — amikor kiállítják, kézbesítik, visszavonják vagy megtekintik őket. Ahelyett, hogy lekérdeznéd az API-t, regisztrálsz egy HTTPS-végpontot, és a badges.ninja minden feliratkozott eseményhez egy aláírt POST kérést küld rá.

Minden kezelési végpont hitelesítést igényel az X-Api-Key fejlécen keresztül. Lásd: Hitelesítés. Végpontok létrehozásához vagy törléséhez írási jogkörű kulcs szükséges; a listázáshoz olvasási. Lásd: API-kulcsok.

Végpont regisztrálása

POST /webhooks

Paraméterek

Paraméter	Típus	Kötelező	Leírás
url	string	Igen	A HTTPS-végpontod. https:// előtaggal kell kezdődnie.
events	string[]	Nem	Az események típusai, amelyekre feliratkozol. Hagyd ki, vagy add meg a ["*"] értéket az összes esemény fogadásához.

Példa

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

Válasz

201 Created. Az aláíró titkos kulcsot csak egyszer adjuk vissza — mentsd el most; később nem tudod újra lekérni.

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

Végpontok listázása

GET /webhooks

Visszaadja a regisztrált végpontjaidat. Az aláíró titkos kulcsok soha nem szerepelnek benne.

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

Végpont törlése

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"

A végpontra irányuló kézbesítések azonnal leállnak.

Eseménytípusok

Esemény	Akkor tüzel, amikor…
credential.issued	Egy hitelesítő adatot kiállítanak egy címzettnek.
credential.delivered	Egy hitelesítő adat értesítő e-mailjét elküldik a címzettnek (egyenként vagy tömegesen).
credential.revoked	Egy hitelesítő adatot visszavonnak.
credential.viewed	Egy címzett nyilvános hitelesítőoldalát először megtekintik.

Kézbesítési tartalom

Minden kézbesítés egy POST kérés, amelynek JSON-törzse a következő alakú:

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

Mező	Leírás
id	Egyedi kézbesítési azonosító (használd deduplikáláshoz).
type	Az esemény típusa.
createdAt	Az esemény időbélyege (ezredmásodperc, epoch).
data	Az eseményspecifikus tartalom (lásd alább).

A data eseménytípusonként

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

Kérésfejlécek

Minden kézbesítés a következő fejléceket hordozza:

Fejléc	Leírás
X-Bws-Event	Az esemény típusa (megegyezik a törzsben lévő type értékkel).
X-Bws-Delivery	A kézbesítés azonosítója (megegyezik a törzsben lévő id értékkel).
X-Bws-Signature	sha256= utána a kérés nyers törzsének HMAC-SHA256 értéke, a végpontod titkos kulcsával kulcsolva.
User-Agent	badges.ninja-webhooks/1

Aláírások ellenőrzése

Mindig ellenőrizd az aláírást, mielőtt megbíznál egy kézbesítésben. Számítsd ki a kérés nyers törzsének HMAC-SHA256 értékét a végpontod aláíró titkos kulcsával, és hasonlítsd össze (állandó időben) az X-Bws-Signature fejléccel.

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);
}

A pontosan azokat a bájtokat használd, amelyeket megkaptál — a JSON előbb elemzése és újraszerializálása megváltoztatja a bájtokat, és érvényteleníti az aláírást.

Újrapróbálkozások és megbízhatóság

• Egy kézbesítés sikeresnek számít, amikor a végpontod 2xx státusszal válaszol.
• A sikertelen kézbesítéseket néhányszor újrapróbáljuk. A folyamatosan hibázó végpontok failureCount értéket halmoznak fel; 20 egymást követő hiba után a végpont automatikusan letiltásra kerül (active: false), és leáll a kézbesítések fogadása, amíg meg nem javítod, és nem regisztrálsz egy új végpontot.
• A kézbesítések többször is megérkezhetnek. Használd az X-Bws-Delivery azonosítót (vagy a törzsben lévő id értéket), hogy a kezelőd idempotens legyen.
• Válaszolj gyorsan (kb. 10 másodpercen belül). A nagy erőforrásigényű munkát a nyugtázás után, aszinkron módon végezd.

Webhookok kezelése az irányítópulton

A végpontokat API nélkül is kezelheted — nyisd meg a Webhooks menüpontot az irányítópult oldalsávjában, hogy hozzáadd, listázd és töröld a végpontokat, és kiválaszd, melyik milyen eseményeket kap.