API Webhook

I webhook notificano la tua applicazione in tempo reale quando accade qualcosa alle tue credenziali — quando ne viene rilasciata, consegnata, revocata o visualizzata una. Invece di interrogare l'API, registri un endpoint HTTPS e badges.ninja gli invia un POST firmato per ogni evento a cui ti abboni.

Tutti gli endpoint di gestione richiedono l'autenticazione tramite l'header X-Api-Key. Vedi Autenticazione. Creare o eliminare endpoint richiede una chiave con scope write; l'elenco richiede read. Vedi Chiavi API.

Registrare un endpoint

POST /webhooks

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
url	string	Sì	Il tuo endpoint HTTPS. Deve iniziare con https://.
events	string[]	No	Tipi di evento a cui abbonarsi. Ometti o passa ["*"] per ricevere tutti gli eventi.

Esempio

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

Risposta

201 Created. Il secret di firma viene restituito una sola volta — conservalo ora; non potrai recuperarlo di nuovo.

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

Elencare gli endpoint

GET /webhooks

Restituisce gli endpoint registrati. I secret di firma non sono mai inclusi.

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

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

Le consegne verso l'endpoint si interrompono immediatamente.

Tipi di evento

Evento	Si attiva quando…
credential.issued	Una credenziale viene rilasciata a un destinatario.
credential.delivered	L'email di notifica di una credenziale viene inviata al destinatario (singola o in blocco).
credential.revoked	Una credenziale viene revocata.
credential.viewed	La pagina pubblica di una credenziale di un destinatario viene visualizzata per la prima volta.

Payload di consegna

Ogni consegna è un POST con un corpo JSON di questa forma:

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

Campo	Descrizione
id	Id univoco della consegna (usalo per deduplicare).
type	Il tipo di evento.
createdAt	Timestamp dell'evento (millisecondi epoch).
data	Payload specifico dell'evento (vedi sotto).

data per tipo di evento

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

Header della richiesta

Ogni consegna trasporta questi header:

Header	Descrizione
X-Bws-Event	Il tipo di evento (identico a type nel corpo).
X-Bws-Delivery	L'id della consegna (identico a id nel corpo).
X-Bws-Signature	sha256= seguito dall'HMAC-SHA256 del corpo grezzo della richiesta, con chiave il secret del tuo endpoint.
User-Agent	badges.ninja-webhooks/1

Verificare le firme

Verifica sempre la firma prima di fidarti di una consegna. Calcola l'HMAC-SHA256 del corpo grezzo della richiesta usando il secret di firma del tuo endpoint e confrontalo (in tempo costante) con l'header 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);
}

Usa esattamente i byte che hai ricevuto — effettuare prima il parsing e la ri-serializzazione del JSON cambierà i byte e invaliderà la firma.

Nuovi tentativi e affidabilità

• Una consegna è considerata riuscita quando il tuo endpoint risponde con uno stato 2xx.
• Le consegne fallite vengono ritentate un numero limitato di volte. Gli endpoint che continuano a fallire accumulano un failureCount; dopo 20 fallimenti consecutivi un endpoint viene disattivato automaticamente (active: false) e smette di ricevere consegne finché non lo correggi e registri un nuovo endpoint.
• Le consegne possono arrivare più di una volta. Usa l'id X-Bws-Delivery (o l'id nel corpo) per rendere idempotente il tuo handler.
• Rispondi rapidamente (entro ~10 secondi). Esegui il lavoro pesante in modo asincrono dopo aver confermato la ricezione.

Gestire i webhook nella dashboard

Puoi anche gestire gli endpoint senza l'API — apri Webhooks nella barra laterale della dashboard per aggiungere, elencare ed eliminare endpoint e scegliere quali eventi riceve ciascuno.