Webhooks-API

Webhooks stellen je applicatie in realtime op de hoogte wanneer er iets met je credentials gebeurt — wanneer er een wordt uitgegeven, afgeleverd, ingetrokken of bekeken. In plaats van de API te pollen, registreer je een HTTPS-endpoint en stuurt badges.ninja het een ondertekende POST voor elke gebeurtenis waarop je je abonneert.

Alle beheerendpoints vereisen authenticatie via de X-Api-Key-header. Zie Authenticatie. Het aanmaken of verwijderen van endpoints vereist een sleutel met write-scope; het opsommen vereist read. Zie API-sleutels.

Een endpoint registreren

POST /webhooks

Parameters

Parameter	Type	Verplicht	Beschrijving
url	string	Ja	Je HTTPS-endpoint. Moet met https:// beginnen.
events	string[]	Nee	Gebeurtenistypen om je op te abonneren. Laat weg of geef ["*"] door om alle gebeurtenissen te ontvangen.

Voorbeeld

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

Antwoord

201 Created. Het ondertekeningsgeheim wordt slechts één keer teruggegeven — bewaar het nu; je kunt het niet opnieuw ophalen.

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

Endpoints opsommen

GET /webhooks

Geeft je geregistreerde endpoints terug. Ondertekeningsgeheimen worden nooit meegestuurd.

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

Een endpoint verwijderen

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"

Afleveringen naar het endpoint stoppen onmiddellijk.

Gebeurtenistypen

Gebeurtenis	Wordt geactiveerd wanneer…
credential.issued	Een credential aan een ontvanger wordt uitgegeven.
credential.delivered	De notificatie-e-mail van een credential naar de ontvanger wordt verzonden (afzonderlijk of in bulk).
credential.revoked	Een credential wordt ingetrokken.
credential.viewed	De openbare credentialpagina van een ontvanger voor de eerste keer wordt bekeken.

Afleveringspayload

Elke aflevering is een POST met een JSON-body van deze vorm:

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

Veld	Beschrijving
id	Unieke afleverings-id (gebruik deze om te dedupliceren).
type	Het gebeurtenistype.
createdAt	Tijdstempel van de gebeurtenis (epoch-milliseconden).
data	Gebeurtenisspecifieke payload (zie hieronder).

data per gebeurtenistype

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

Request-headers

Elke aflevering draagt deze headers:

Header	Beschrijving
X-Bws-Event	Het gebeurtenistype (hetzelfde als type in de body).
X-Bws-Delivery	De afleverings-id (hetzelfde als id in de body).
X-Bws-Signature	sha256= gevolgd door de HMAC-SHA256 van de ruwe request-body, met het geheim van je endpoint als sleutel.
User-Agent	badges.ninja-webhooks/1

Handtekeningen verifiëren

Verifieer altijd de handtekening voordat je een aflevering vertrouwt. Bereken de HMAC-SHA256 van de ruwe request-body met het ondertekeningsgeheim van je endpoint en vergelijk deze (in constante tijd) met de X-Bws-Signature-header.

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

Gebruik exact de bytes die je hebt ontvangen — de JSON eerst parsen en opnieuw serialiseren verandert de bytes en breekt de handtekening.

Nieuwe pogingen & betrouwbaarheid

• Een aflevering wordt als geslaagd beschouwd wanneer je endpoint met een 2xx-status antwoordt.
• Mislukte afleveringen worden een klein aantal keren opnieuw geprobeerd. Endpoints die blijven falen, bouwen een failureCount op; na 20 opeenvolgende mislukkingen wordt een endpoint automatisch uitgeschakeld (active: false) en ontvangt het geen afleveringen meer totdat je het herstelt en een nieuw endpoint registreert.
• Afleveringen kunnen meer dan één keer aankomen. Gebruik de X-Bws-Delivery-id (of de id in de body) om je handler idempotent te maken.
• Antwoord snel (binnen ~10 seconden). Doe zwaar werk asynchroon nadat je de ontvangst hebt bevestigd.

Webhooks beheren in het dashboard

Je kunt endpoints ook zonder de API beheren — open Webhooks in de zijbalk van het dashboard om endpoints toe te voegen, op te sommen en te verwijderen en te kiezen welke gebeurtenissen elk endpoint ontvangt.