Webhooks API

Webhooks meddelar din applikation i realtid när saker händer med dina intyg — när ett utfärdas, levereras, återkallas eller visas. I stället för att polla API:et registrerar du en HTTPS-slutpunkt och badges.ninja skickar en signerad POST för varje händelse du prenumererar på.

Alla hanteringsslutpunkter kräver autentisering via X-Api-Key-headern. Se Autentisering. Att skapa eller ta bort slutpunkter kräver en nyckel med write-område; att lista kräver read. Se API-nycklar.

Registrera en slutpunkt

POST /webhooks

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
url	string	Ja	Din HTTPS-slutpunkt. Måste börja med https://.
events	string[]	Nej	Händelsetyper att prenumerera på. Utelämna eller skicka ["*"] för att ta emot alla händelser.

Exempel

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. Signeringshemligheten returneras endast en gång — spara den nu; du kan inte hämta den igen.

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

Lista slutpunkter

GET /webhooks

Returnerar dina registrerade slutpunkter. Signeringshemligheter inkluderas 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
    }
  ]
}

Ta bort en slutpunkt

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 till slutpunkten stoppar omedelbart.

Händelsetyper

Händelse	Utlöses när…
credential.issued	Ett intyg utfärdas till en mottagare.
credential.delivered	Ett intygs aviseringsmejl skickas till mottagaren (enskilt eller i bulk).
credential.revoked	Ett intyg återkallas.
credential.viewed	En mottagares offentliga intygssida visas för första gången.

Leveransnyttolast

Varje leverans är en POST med en JSON-body av denna form:

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

Fält	Beskrivning
id	Unikt leverans-id (använd det för att avduplicera).
type	Händelsetypen.
createdAt	Händelsens tidsstämpel (epoch-millisekunder).
data	Händelsespecifik nyttolast (se nedan).

data per händelsetyp

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

Begäranheaders

Varje leverans bär dessa headers:

Header	Beskrivning
X-Bws-Event	Händelsetypen (samma som type i bodyn).
X-Bws-Delivery	Leverans-id:t (samma som id i bodyn).
X-Bws-Signature	sha256= följt av HMAC-SHA256 av den råa begäranbodyn, nycklad med din slutpunktshemlighet.
User-Agent	badges.ninja-webhooks/1

Verifiera signaturer

Verifiera alltid signaturen innan du litar på en leverans. Beräkna HMAC-SHA256 av den råa begäranbodyn med din slutpunkts signeringshemlighet, och jämför den (i konstant tid) med X-Bws-Signature-headern.

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

Använd exakt de bytes du tog emot — att parsa och serialisera om JSON:en först ändrar bytena och bryter signaturen.

Omförsök och tillförlitlighet

• En leverans anses lyckad när din slutpunkt svarar med en 2xx-status.
• Misslyckade leveranser görs om ett litet antal gånger. Slutpunkter som fortsätter att misslyckas ackumulerar en failureCount; efter 20 på varandra följande misslyckanden inaktiveras en slutpunkt automatiskt (active: false) och slutar ta emot leveranser tills du åtgärdar den och registrerar en ny slutpunkt.
• Leveranser kan komma fram mer än en gång. Använd X-Bws-Delivery-id:t (eller id i bodyn) för att göra din hanterare idempotent.
• Svara snabbt (inom ~10 sekunder). Utför tungt arbete asynkront efter att du bekräftat.

Hantera webhooks i instrumentpanelen

Du kan också hantera slutpunkter utan API:et — öppna Webhooks i instrumentpanelens sidofält för att lägga till, lista och ta bort slutpunkter och välja vilka händelser var och en tar emot.