Webhooks API

Webhooks giver din applikation besked i realtid, når der sker noget med dine beviser — når et udstedes, leveres, tilbagekaldes eller vises. I stedet for at polle API'et registrerer du et HTTPS-endpoint, og badges.ninja sender det en signeret POST for hver hændelse, du abonnerer på.

Alle administrationsendpoints kræver godkendelse via X-Api-Key-headeren. Se Godkendelse. Oprettelse eller sletning af endpoints kræver en nøgle med write-område; listning kræver read. Se API-nøgler.

Registrér et endpoint

POST /webhooks

Parametre

Parameter	Type	Påkrævet	Beskrivelse
url	string	Ja	Dit HTTPS-endpoint. Skal begynde med https://.
events	string[]	Nej	Hændelsestyper at abonnere på. Udelad eller send ["*"] for at modtage alle hændelser.

Eksempel

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

Svar

201 Created. Signeringshemmeligheden returneres kun én gang — gem den nu; du kan ikke hente den igen.

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

Vis endpoints

GET /webhooks

Returnerer dine registrerede endpoints. Signeringshemmeligheder inkluderes aldrig.

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

Slet et 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"

Leveringer til endpointet stopper med det samme.

Hændelsestyper

Hændelse	Udløses, når…
credential.issued	Et bevis udstedes til en modtager.
credential.delivered	Et bevis' notifikationsmail sendes til modtageren (enkeltvis eller i bulk).
credential.revoked	Et bevis tilbagekaldes.
credential.viewed	En modtagers offentlige bevisside vises for første gang.

Leveringspayload

Hver levering er en POST med en JSON-body af denne form:

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

Felt	Beskrivelse
id	Unikt leverings-id (brug det til at fjerne dubletter).
type	Hændelsestypen.
createdAt	Hændelsens tidsstempel (epoch-millisekunder).
data	Hændelsesspecifik payload (se nedenfor).

data efter hændelsestype

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

Forespørgselsheaders

Hver levering bærer disse headers:

Header	Beskrivelse
X-Bws-Event	Hændelsestypen (samme som type i bodyen).
X-Bws-Delivery	Leverings-id'et (samme som id i bodyen).
X-Bws-Signature	sha256= efterfulgt af HMAC-SHA256 af den rå forespørgselsbody, nøglet med din endpoint-hemmelighed.
User-Agent	badges.ninja-webhooks/1

Verificering af signaturer

Verificér altid signaturen, før du stoler på en levering. Beregn HMAC-SHA256 af den rå forespørgselsbody med dit endpoints signeringshemmelighed, og sammenlign den (i konstant tid) med X-Bws-Signature-headeren.

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

Brug præcis de bytes, du modtog — at parse og re-serialisere JSON'en først ændrer bytesne og bryder signaturen.

Gentagelser og pålidelighed

• En levering betragtes som vellykket, når dit endpoint svarer med en 2xx-status.
• Mislykkede leveringer gentages et lille antal gange. Endpoints, der bliver ved med at fejle, akkumulerer en failureCount; efter 20 på hinanden følgende fejl deaktiveres et endpoint automatisk (active: false) og holder op med at modtage leveringer, indtil du retter det og registrerer et nyt endpoint.
• Leveringer kan ankomme mere end én gang. Brug X-Bws-Delivery-id'et (eller id i bodyen) til at gøre din handler idempotent.
• Svar hurtigt (inden for ~10 sekunder). Udfør tungt arbejde asynkront, efter du har kvitteret.

Administration af webhooks i dashboardet

Du kan også administrere endpoints uden API'et — åbn Webhooks i dashboardets sidebjælke for at tilføje, vise og slette endpoints og vælge, hvilke hændelser hvert enkelt modtager.