API de Webhooks

Els webhooks notifiquen la teva aplicació en temps real quan passa alguna cosa amb les teves credencials: quan se n'emet, se'n lliura, se'n revoca o se'n visualitza una. En lloc de sondejar l'API, registres un endpoint HTTPS i badges.ninja li envia un POST signat per cada esdeveniment al qual et subscrius.

Tots els endpoints de gestió requereixen autenticació mitjançant la capçalera X-Api-Key. Consulta Autenticació. Crear o esborrar endpoints requereix una clau amb àmbit d'escriptura; llistar requereix lectura. Consulta Claus API.

Registrar un endpoint

POST /webhooks

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
url	string	Sí	El teu endpoint HTTPS. Ha de començar per https://.
events	string[]	No	Tipus d'esdeveniment als quals subscriure's. Omet-lo o passa ["*"] per rebre tots els esdeveniments.

Exemple

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

Resposta

201 Created. El secret de signatura es retorna només una vegada: desa'l ara; no el podràs recuperar de nou.

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

Llistar endpoints

GET /webhooks

Retorna els teus endpoints registrats. Els secrets de signatura mai s'hi inclouen.

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

Esborrar un 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"

Els lliuraments a l'endpoint s'aturen immediatament.

Tipus d'esdeveniment

Esdeveniment	Es dispara quan…
credential.issued	S'emet una credencial a un destinatari.
credential.delivered	S'envia al destinatari el correu de notificació d'una credencial (individual o massiu).
credential.revoked	Es revoca una credencial.
credential.viewed	Es visualitza per primera vegada la pàgina pública de la credencial d'un destinatari.

Cos del lliurament (payload)

Cada lliurament és un POST amb un cos JSON amb aquesta forma:

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

Camp	Descripció
id	Id únic del lliurament (fes-lo servir per eliminar duplicats).
type	El tipus d'esdeveniment.
createdAt	Marca de temps de l'esdeveniment (mil·lisegons epoch).
data	Payload específic de l'esdeveniment (vegeu més avall).

data per tipus d'esdeveniment

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

Capçaleres de la sol·licitud

Cada lliurament porta aquestes capçaleres:

Capçalera	Descripció
X-Bws-Event	El tipus d'esdeveniment (igual que type al cos).
X-Bws-Delivery	L'id del lliurament (igual que id al cos).
X-Bws-Signature	sha256= seguit de l'HMAC-SHA256 del cos brut de la sol·licitud, amb clau el secret del teu endpoint.
User-Agent	badges.ninja-webhooks/1

Verificar signatures

Verifica sempre la signatura abans de confiar en un lliurament. Calcula l'HMAC-SHA256 del cos brut de la sol·licitud fent servir el secret de signatura del teu endpoint i compara'l (en temps constant) amb la capçalera 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);
}

Fes servir exactament els bytes que has rebut: analitzar i tornar a serialitzar el JSON abans canviarà els bytes i trencarà la signatura.

Reintents i fiabilitat

• Un lliurament es considera correcte quan el teu endpoint respon amb un estat 2xx.
• Els lliuraments fallits es reintenten un nombre reduït de vegades. Els endpoints que continuen fallant acumulen un failureCount; després de 20 fallades consecutives, un endpoint es desactiva automàticament (active: false) i deixa de rebre lliuraments fins que el corregeixis i registris un endpoint nou.
• Els lliuraments poden arribar més d'una vegada. Fes servir l'id X-Bws-Delivery (o l'id del cos) per fer que el teu gestor sigui idempotent.
• Respon amb rapidesa (en uns ~10 segons). Fes la feina pesant de manera asíncrona després de confirmar-ne la recepció.

Gestionar webhooks al tauler

També pots gestionar els endpoints sense l'API: obre Webhooks a la barra lateral del tauler per afegir, llistar i esborrar endpoints i triar quins esdeveniments rep cadascun.