Webhooks API

Webhooks varsler applikasjonen din i sanntid når det skjer noe med bevisene dine — når ett utstedes, leveres, tilbakekalles eller vises. I stedet for å polle API-et registrerer du et HTTPS-endepunkt, og badges.ninja sender det en signert POST for hver hendelse du abonnerer på.

Alle administrasjonsendepunkter krever autentisering via X-Api-Key-headeren. Se Autentisering. Å opprette eller slette endepunkter krever en nøkkel med write-område; listing krever read. Se API-nøkler.

Registrer et endepunkt

POST /webhooks

Parametere

Parameter	Type	Påkrevd	Beskrivelse
url	string	Ja	HTTPS-endepunktet ditt. Må begynne med https://.
events	string[]	Nei	Hendelsestyper å abonnere på. Utelat eller send ["*"] for å motta alle hendelser.

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. Signeringshemmeligheten returneres kun én gang — lagre den nå; du kan ikke hente den igjen.

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

List opp endepunkter

GET /webhooks

Returnerer de registrerte endepunktene dine. Signeringshemmeligheter inkluderes aldri.

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

Slett et endepunkt

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"

Leveranser til endepunktet stopper umiddelbart.

Hendelsestyper

Hendelse	Utløses når…
credential.issued	Et bevis utstedes til en mottaker.
credential.delivered	Et bevis' varsel-e-post sendes til mottakeren (enkeltvis eller i bulk).
credential.revoked	Et bevis tilbakekalles.
credential.viewed	En mottakers offentlige bevisside vises for første gang.

Leveranse-nyttelast

Hver leveranse er en POST med en JSON-body av denne formen:

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

Felt	Beskrivelse
id	Unik leveranse-id (bruk den til å fjerne duplikater).
type	Hendelsestypen.
createdAt	Hendelsens tidsstempel (epoch-millisekunder).
data	Hendelsesspesifikk nyttelast (se nedenfor).

data etter hendelsestype

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ørselsheadere

Hver leveranse bærer disse headerne:

Header	Beskrivelse
X-Bws-Event	Hendelsestypen (samme som type i bodyen).
X-Bws-Delivery	Leveranse-id-en (samme som id i bodyen).
X-Bws-Signature	sha256= etterfulgt av HMAC-SHA256 av den rå forespørselsbodyen, nøklet med endepunkthemmeligheten din.
User-Agent	badges.ninja-webhooks/1

Verifisere signaturer

Verifiser alltid signaturen før du stoler på en leveranse. Beregn HMAC-SHA256 av den rå forespørselsbodyen med endepunktets signeringshemmelighet, 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);
}

Bruk nøyaktig de bytene du mottok — å parse og re-serialisere JSON-en først endrer bytene og bryter signaturen.

Nye forsøk og pålitelighet

• En leveranse regnes som vellykket når endepunktet ditt svarer med en 2xx-status.
• Mislykkede leveranser prøves på nytt et lite antall ganger. Endepunkter som fortsetter å feile, akkumulerer en failureCount; etter 20 påfølgende feil deaktiveres et endepunkt automatisk (active: false) og slutter å motta leveranser til du retter det og registrerer et nytt endepunkt.
• Leveranser kan komme frem mer enn én gang. Bruk X-Bws-Delivery-id-en (eller id i bodyen) for å gjøre handleren din idempotent.
• Svar raskt (innen ~10 sekunder). Utfør tungt arbeid asynkront etter at du har bekreftet.

Administrere webhooks i dashbordet

Du kan også administrere endepunkter uten API-et — åpne Webhooks i dashbordets sidefelt for å legge til, liste opp og slette endepunkter og velge hvilke hendelser hvert enkelt mottar.