> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boble.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Vérification de signature

> Pourquoi l'en-tête Boble-Signature compte, et comment le vérifier avant de faire confiance à un événement.

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.

<Warning>
  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.
</Warning>

## L'en-tête `Boble-Signature`

Chaque livraison transporte un en-tête de cette forme :

```http theme={null}
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 :

<Steps>
  <Step title="Extraire t et v1 de l'en-tête">
    Coupez la valeur sur `,`, puis chaque part sur `=`.
  </Step>

  <Step title="Recalculer la signature de votre côté">
    Calculez `HMAC-SHA256(secret, "<t>.<rawBody>")` et encodez en hexadécimal.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

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.