API Webhooks

Les webhooks notifient votre application en temps réel lorsqu'un événement survient sur vos credentials — lorsqu'un credential est émis, délivré, révoqué ou consulté. Au lieu d'interroger l'API, vous enregistrez un point de terminaison HTTPS et badges.ninja lui envoie un POST signé pour chaque événement auquel vous vous abonnez.

Tous les points de terminaison de gestion nécessitent une authentification via l'en-tête X-Api-Key. Voir Authentification. La création ou la suppression de points de terminaison nécessite une clé avec le scope write ; le listage nécessite read. Voir Clés API.

Enregistrer un point de terminaison

POST /webhooks

Paramètres

Paramètre	Type	Requis	Description
url	string	Oui	Votre point de terminaison HTTPS. Doit commencer par https://.
events	string[]	Non	Types d'événements auxquels s'abonner. Omettez ou passez ["*"] pour recevoir tous les événements.

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

Réponse

201 Created. Le secret de signature n'est renvoyé qu'une seule fois — conservez-le maintenant ; vous ne pourrez plus le récupérer.

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

Lister les points de terminaison

GET /webhooks

Renvoie vos points de terminaison enregistrés. Les secrets de signature ne sont jamais inclus.

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

Supprimer un point de terminaison

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"

Les livraisons vers ce point de terminaison s'arrêtent immédiatement.

Types d'événements

Événement	Se déclenche lorsque…
credential.issued	Un credential est émis à un destinataire.
credential.delivered	L'e-mail de notification d'un credential est envoyé au destinataire (individuel ou en masse).
credential.revoked	Un credential est révoqué.
credential.viewed	La page publique d'un credential est consultée pour la première fois.

Charge utile de livraison

Chaque livraison est un POST avec un corps JSON de cette forme :

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

Champ	Description
id	Identifiant unique de livraison (utilisez-le pour dédupliquer).
type	Le type d'événement.
createdAt	Horodatage de l'événement (millisecondes epoch).
data	Charge utile spécifique à l'événement (voir ci-dessous).

data par type d'événement

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

En-têtes de requête

Chaque livraison transporte ces en-têtes :

En-tête	Description
X-Bws-Event	Le type d'événement (identique à type dans le corps).
X-Bws-Delivery	L'identifiant de livraison (identique à id dans le corps).
X-Bws-Signature	sha256= suivi du HMAC-SHA256 du corps brut de la requête, avec le secret de votre point de terminaison comme clé.
User-Agent	badges.ninja-webhooks/1

Vérifier les signatures

Vérifiez toujours la signature avant de faire confiance à une livraison. Calculez le HMAC-SHA256 du corps brut de la requête en utilisant le secret de signature de votre point de terminaison, et comparez-le (en temps constant) à l'en-tête 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);
}

Utilisez exactement les octets que vous avez reçus — analyser puis re-sérialiser le JSON au préalable modifiera les octets et cassera la signature.

Nouvelles tentatives et fiabilité

• Une livraison est considérée comme réussie lorsque votre point de terminaison répond avec un statut 2xx.
• Les livraisons échouées font l'objet d'un petit nombre de nouvelles tentatives. Les points de terminaison qui continuent d'échouer accumulent un failureCount ; après 20 échecs consécutifs, un point de terminaison est automatiquement désactivé (active: false) et cesse de recevoir des livraisons jusqu'à ce que vous le corrigiez et enregistriez un nouveau point de terminaison.
• Les livraisons peuvent arriver plus d'une fois. Utilisez l'identifiant X-Bws-Delivery (ou le id du corps) pour rendre votre gestionnaire idempotent.
• Répondez rapidement (en moins de ~10 secondes). Effectuez les traitements lourds de manière asynchrone après avoir accusé réception.

Gérer les webhooks dans le tableau de bord

Vous pouvez également gérer les points de terminaison sans l'API — ouvrez Webhooks dans la barre latérale du tableau de bord pour ajouter, lister et supprimer des points de terminaison et choisir les événements que chacun reçoit.