Webhooks API

Webhooki powiadamiają Twoją aplikację w czasie rzeczywistym o zdarzeniach dotyczących Twoich poświadczeń — gdy zostaną wystawione, dostarczone, unieważnione lub wyświetlone. Zamiast odpytywać API, rejestrujesz endpoint HTTPS, a badges.ninja wysyła na niego podpisany POST dla każdego zdarzenia, które subskrybujesz.

Wszystkie endpointy zarządzania wymagają uwierzytelnienia za pomocą nagłówka X-Api-Key. Zobacz Uwierzytelnianie. Tworzenie lub usuwanie endpointów wymaga klucza z zakresem write; wyświetlanie listy wymaga read. Zobacz Klucze API.

Rejestracja endpointu

POST /webhooks

Parametry

Parametr	Typ	Wymagany	Opis
url	string	Tak	Twój endpoint HTTPS. Musi zaczynać się od https://.
events	string[]	Nie	Typy zdarzeń do subskrypcji. Pomiń lub przekaż ["*"], aby otrzymywać wszystkie zdarzenia.

Przykład

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

Odpowiedź

201 Created. Sekret podpisujący jest zwracany tylko raz — zapisz go teraz; nie można go pobrać ponownie.

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

Lista endpointów

GET /webhooks

Zwraca Twoje zarejestrowane endpointy. Sekrety podpisujące nigdy nie są dołączane.

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

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

Dostarczenia do endpointu zatrzymują się natychmiast.

Typy zdarzeń

Zdarzenie	Wyzwalane, gdy…
credential.issued	Poświadczenie zostaje wystawione odbiorcy.
credential.delivered	E-mail z powiadomieniem o poświadczeniu zostaje wysłany do odbiorcy (pojedynczo lub masowo).
credential.revoked	Poświadczenie zostaje unieważnione.
credential.viewed	Publiczna strona poświadczenia odbiorcy zostaje wyświetlona po raz pierwszy.

Ładunek dostarczenia

Każde dostarczenie to POST z treścią JSON o następującym kształcie:

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

Pole	Opis
id	Unikalny identyfikator dostarczenia (użyj go do deduplikacji).
type	Typ zdarzenia.
createdAt	Znacznik czasu zdarzenia (milisekundy epoki).
data	Ładunek specyficzny dla zdarzenia (patrz poniżej).

data według typu zdarzenia

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

Nagłówki żądania

Każde dostarczenie niesie te nagłówki:

Nagłówek	Opis
X-Bws-Event	Typ zdarzenia (taki sam jak type w treści).
X-Bws-Delivery	Identyfikator dostarczenia (taki sam jak id w treści).
X-Bws-Signature	sha256=, po którym następuje HMAC-SHA256 surowej treści żądania, z kluczem będącym sekretem Twojego endpointu.
User-Agent	badges.ninja-webhooks/1

Weryfikacja podpisów

Zawsze weryfikuj podpis, zanim zaufasz dostarczeniu. Oblicz HMAC-SHA256 surowej treści żądania, używając sekretu podpisującego Twojego endpointu, i porównaj go (w stałym czasie) z nagłówkiem 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);
}

Użyj dokładnie tych bajtów, które otrzymałeś — sparsowanie i ponowna serializacja JSON zmieni bajty i uszkodzi podpis.

Ponowne próby i niezawodność

• Dostarczenie jest uznawane za udane, gdy Twój endpoint odpowie statusem 2xx.
• Nieudane dostarczenia są ponawiane niewielką liczbę razy. Endpointy, które nadal zawodzą, gromadzą failureCount; po 20 kolejnych niepowodzeniach endpoint jest automatycznie wyłączany (active: false) i przestaje otrzymywać dostarczenia, dopóki nie naprawisz problemu i nie zarejestrujesz nowego endpointu.
• Dostarczenia mogą przychodzić więcej niż raz. Użyj identyfikatora X-Bws-Delivery (lub id z treści), aby Twój handler był idempotentny.
• Odpowiadaj szybko (w ciągu ~10 sekund). Ciężką pracę wykonuj asynchronicznie po potwierdzeniu.

Zarządzanie webhookami w panelu

Możesz też zarządzać endpointami bez API — otwórz Webhooks na pasku bocznym panelu, aby dodawać, wyświetlać i usuwać endpointy oraz wybierać, które zdarzenia otrzymuje każdy z nich.