API Webhooks

Webhook-urile notifică aplicația ta în timp real când se întâmplă ceva cu credențialele tale — când una este emisă, livrată, revocată sau vizualizată. În loc să interoghezi API-ul, înregistrezi un endpoint HTTPS, iar badges.ninja îi trimite un POST semnat pentru fiecare eveniment la care te-ai abonat.

Toate endpoint-urile de gestionare necesită autentificare prin antetul X-Api-Key. Vezi Autentificare. Crearea sau ștergerea endpoint-urilor necesită o cheie cu domeniu de scriere; listarea necesită citire. Vezi Chei API.

Înregistrarea unui endpoint

POST /webhooks

Parametri

Parametru	Tip	Obligatoriu	Descriere
url	string	Da	Endpoint-ul tău HTTPS. Trebuie să înceapă cu https://.
events	string[]	Nu	Tipurile de evenimente la care te abonezi. Omite sau transmite ["*"] pentru a primi toate evenimentele.

Exemplu

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

Răspuns

201 Created. Secretul de semnare este returnat o singură dată — stochează-l acum; nu îl mai poți recupera.

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

Listarea endpoint-urilor

GET /webhooks

Returnează endpoint-urile înregistrate. Secretele de semnare nu sunt incluse niciodată.

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

Ștergerea unui endpoint

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"

Livrările către endpoint se opresc imediat.

Tipuri de evenimente

Eveniment	Se declanșează când…
credential.issued	O credențială este emisă către un destinatar.
credential.delivered	E-mailul de notificare al unei credențiale este trimis destinatarului (individual sau în masă).
credential.revoked	O credențială este revocată.
credential.viewed	Pagina publică a credențialei unui destinatar este vizualizată pentru prima dată.

Conținutul livrării

Fiecare livrare este un POST cu un corp JSON de această formă:

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

Câmp	Descriere
id	ID unic al livrării (folosește-l pentru deduplicare).
type	Tipul evenimentului.
createdAt	Marca temporală a evenimentului (milisecunde epoch).
data	Conținutul specific evenimentului (vezi mai jos).

data în funcție de tipul evenimentului

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

Anteturile solicitării

Fiecare livrare poartă aceste anteturi:

Antet	Descriere
X-Bws-Event	Tipul evenimentului (identic cu type din corp).
X-Bws-Delivery	ID-ul livrării (identic cu id din corp).
X-Bws-Signature	sha256= urmat de HMAC-SHA256 al corpului brut al solicitării, cu cheia secretului endpoint-ului tău.
User-Agent	badges.ninja-webhooks/1

Verificarea semnăturilor

Verifică întotdeauna semnătura înainte de a avea încredere într-o livrare. Calculează HMAC-SHA256 al corpului brut al solicitării folosind secretul de semnare al endpoint-ului tău și compară-l (în timp constant) cu antetul 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);
}

Folosește exact octeții pe care i-ai primit — analizarea și reserializarea JSON-ului mai întâi va modifica octeții și va invalida semnătura.

Reîncercări și fiabilitate

• O livrare este considerată reușită când endpoint-ul tău răspunde cu un status 2xx.
• Livrările eșuate sunt reîncercate de un număr mic de ori. Endpoint-urile care eșuează în continuare acumulează un failureCount; după 20 de eșecuri consecutive, un endpoint este dezactivat automat (active: false) și încetează să primească livrări până când îl repari și înregistrezi un endpoint nou.
• Livrările pot ajunge de mai multe ori. Folosește ID-ul X-Bws-Delivery (sau id din corp) pentru ca handler-ul tău să fie idempotent.
• Răspunde rapid (în ~10 secunde). Efectuează operațiunile grele asincron, după confirmare.

Gestionarea webhook-urilor în panou

Poți gestiona endpoint-urile și fără API — deschide Webhooks din bara laterală a panoului pentru a adăuga, lista și șterge endpoint-uri și pentru a alege ce evenimente primește fiecare.