Webhooks API

Webhookovi obavještavaju vašu aplikaciju u stvarnom vremenu kada se nešto dogodi s vašim vjerodajnicama — kada je neka izdana, isporučena, opozvana ili pregledana. Umjesto da ispitujete API, registrirate HTTPS endpoint, a badges.ninja mu šalje potpisani POST za svaki događaj na koji ste se pretplatili.

Svi endpointi za upravljanje zahtijevaju autentifikaciju putem zaglavlja X-Api-Key. Pogledajte Autentifikacija. Stvaranje ili brisanje endpointa zahtijeva ključ s opsegom pisanja; ispis zahtijeva čitanje. Pogledajte API ključevi.

Registracija endpointa

POST /webhooks

Parametri

Parametar	Tip	Obavezno	Opis
url	string	Da	Vaš HTTPS endpoint. Mora počinjati s https://.
events	string[]	Ne	Tipovi događaja na koje se pretplaćujete. Izostavite ili proslijedite ["*"] da primate sve događaje.

Primjer

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

Odgovor

201 Created. Tajni ključ za potpisivanje vraća se samo jednom — pohranite ga sada; ne možete ga ponovno dohvatiti.

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

Ispis endpointa

GET /webhooks

Vraća vaše registrirane endpointe. Tajni ključevi za potpisivanje nikada nisu uključeni.

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

Brisanje endpointa

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"

Isporuke prema endpointu odmah prestaju.

Tipovi događaja

Događaj	Aktivira se kada…
credential.issued	Vjerodajnica je izdana primatelju.
credential.delivered	E-pošta s obavijesti o vjerodajnici poslana je primatelju (pojedinačno ili skupno).
credential.revoked	Vjerodajnica je opozvana.
credential.viewed	Javna stranica vjerodajnice primatelja pregledana je prvi put.

Sadržaj isporuke

Svaka isporuka je POST s JSON tijelom ovog oblika:

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

Polje	Opis
id	Jedinstveni ID isporuke (koristite ga za deduplikaciju).
type	Tip događaja.
createdAt	Vremenska oznaka događaja (epoch milisekunde).
data	Sadržaj specifičan za događaj (pogledajte niže).

data prema tipu događaja

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

Zaglavlja zahtjeva

Svaka isporuka nosi ova zaglavlja:

Zaglavlje	Opis
X-Bws-Event	Tip događaja (isto kao type u tijelu).
X-Bws-Delivery	ID isporuke (isto kao id u tijelu).
X-Bws-Signature	sha256= iza kojeg slijedi HMAC-SHA256 sirovog tijela zahtjeva, ključan tajnim ključem vašeg endpointa.
User-Agent	badges.ninja-webhooks/1

Provjera potpisa

Uvijek provjerite potpis prije nego što vjerujete isporuci. Izračunajte HMAC-SHA256 sirovog tijela zahtjeva koristeći tajni ključ za potpisivanje vašeg endpointa i usporedite ga (u konstantnom vremenu) sa zaglavljem 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);
}

Koristite točno bajtove koje ste primili — prethodno raščlanjivanje i ponovna serijalizacija JSON-a promijenit će bajtove i pokvariti potpis.

Ponovni pokušaji i pouzdanost

• Isporuka se smatra uspješnom kada vaš endpoint odgovori statusom 2xx.
• Neuspjele isporuke ponovno se pokušavaju nekoliko puta. Endpointi koji nastavljaju zakazivati akumuliraju failureCount; nakon 20 uzastopnih neuspjeha endpoint se automatski onemogućuje (active: false) i prestaje primati isporuke dok ga ne popravite i registrirate novi endpoint.
• Isporuke mogu stići više puta. Koristite ID X-Bws-Delivery (ili id iz tijela) kako bi vaš handler bio idempotentan.
• Odgovorite brzo (unutar ~10 sekundi). Zahtjevne poslove obavite asinkrono nakon potvrde.

Upravljanje webhookovima na nadzornoj ploči

Endpointima možete upravljati i bez API-ja — otvorite Webhooks u bočnoj traci nadzorne ploče da dodate, ispišete i obrišete endpointe te odaberete koje događaje svaki od njih prima.