Passer au contenu principal
N’importe qui sur internet connaissant votre URL de webhook pourrait vous envoyer un faux événement en se faisant passer pour Boble. Pour s’en prémunir, chaque livraison Boble est signée avec un secret que vous seul et Boble connaissez. Avant d’agir sur un événement — donner un accès, envoyer un email de bienvenue, retirer un rôle Discord — assurez-vous que la signature est valide.

​
Votre clé de signature

Quand vous activez les webhooks pour la première fois, Boble génère une clé de signature pour votre tenant. La même clé sert à signer les livraisons de toutes les promotions auxquelles vous attachez un webhook. Vous la récupérez depuis votre dashboard et vous pouvez la régénérer à tout moment.
Traitez la clé de signature comme un mot de passe. Ne la mettez jamais dans du code client, ne la commitez jamais dans un dépôt public, et régénérez-la immédiatement en cas de fuite.

​
L’en-tête Boble-Signature

Chaque livraison transporte un en-tête de cette forme : 
Boble-Signature: t=1717497600,v1=5257a869e7ec...
Il a deux parties, séparées par une virgule :
  • t — le timestamp Unix en secondes au moment où Boble a émis l’événement. Identique au champ created du body.
  • v1 — la signature : un HMAC-SHA256 en hexadécimal minuscule sur la chaîne <t>.<rawBody>, avec votre clé de signature.

​
Comment vérifier

La vérification tient en trois étapes :
1

Extraire t et v1 de l'en-tête

Coupez la valeur sur ,, puis chaque part sur =.
2

Recalculer la signature de votre côté

Calculez HMAC-SHA256(secret, "<t>.<rawBody>") et encodez en hexadécimal.
3

Comparer en temps constant

Si votre signature recalculée correspond à v1, l’événement est authentique. Sinon, jetez la requête et répondez 401.
Quelques subtilités à connaître :
  • La signature est calculée sur les octets bruts du body, exactement comme Boble vous les a envoyés. Si votre framework parse le JSON et le re-sérialise avant que vous ne vérifiez la signature, vous obtiendrez une chaîne différente et la vérification échouera. Capturez le body brut avant tout middleware JSON.
  • La comparaison doit être en temps constant. N’utilisez pas une égalité de chaîne classique — la plupart des langages fournissent une fonction dédiée (crypto.timingSafeEqual, hmac.compare_digest, hash_equals, etc.).
  • Il est aussi recommandé de rejeter les événements dont le t a plus de quelques minutes (5 minutes est une bonne valeur par défaut). Ça bloque les attaques par rejeu où quelqu’un capturerait un body signé valide et le rejouerait plus tard.

​
Régénérer la clé de signature

Vous pouvez régénérer la clé de signature depuis votre dashboard à tout moment. Dès que vous le faites :
  • L’ancienne clé cesse immédiatement de signer les nouveaux événements.
  • Tout événement que Boble s’apprêtait à envoyer est signé avec la nouvelle clé.
L’ordre de bascule sûr est :
  1. Déployez la nouvelle clé sur votre receveur en premier.
  2. Puis déclenchez la rotation depuis votre dashboard.
Si vous voulez une transition plus douce, gardez les deux clés actives quelques minutes de votre côté et acceptez celle qui correspond.