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

# Vérifier les signatures des webhooks

> Vérifiez le X-Qwairy-Signature des webhooks d’intégration en Node.js ou en Python, rejetez les horodatages périmés et acceptez deux signatures en rotation.

Vérifiez chaque requête de webhook d’intégration avant de lui faire confiance. Qwairy signe chaque tentative avec le secret de l’endpoint ; une signature valide montre donc que la requête vient de Qwairy et que le corps n’a pas été modifié.

Ne vous fiez pas à la place à un jeton intégré à l’URL de l’endpoint. Chaque clé de l’équipe qui peut lire ses webhooks, clés en lecture seule comprises, reçoit l’URL complète.

## Fonctionnement de la signature

L’en-tête `X-Qwairy-Signature` est `sha256=` suivi du HMAC-SHA256 hexadécimal, calculé avec votre secret de signature, de cette chaîne :

```text theme={null}
<X-Qwairy-Timestamp>.<raw request body>
```

* Utilisez les **octets bruts** du corps, avant tout parsing JSON. Un corps parsé puis resérialisé produit une signature différente.
* `X-Qwairy-Timestamp` est l’heure Unix en secondes à laquelle cette tentative a été signée. Chaque nouvelle tentative est signée à nouveau avec un nouvel horodatage.
* Comparez en temps constant.
* Rejetez les requêtes dont l’horodatage s’écarte de plus de **5 minutes** de votre horloge. Cela limite le rejeu d’une requête interceptée.

## Vérifier votre code avec un vecteur de test

Cet exemple synthétique vous permet de valider votre implémentation. Il utilise le secret `synthetic-signing-secret` et l’horodatage `1793610000`.

```text theme={null}
{"id":"evt_3f2a9c1e-5b7d-4e08-8a41-0c9d6e2b7f10","event":"webhook.test","createdAt":"2026-11-02T09:00:00Z","teamId":"team_synthetic_01","brandId":null,"data":{"message":"Test event from Qwairy."}}
```

```text theme={null}
X-Qwairy-Timestamp: 1793610000
X-Qwairy-Signature: sha256=e4f863963bfe0d0ea94861fd4790f23aacadfc496015ed8bd4127807a8d9be1f
```

La tolérance sur l’horodatage rejette cet exemple avec une horloge réelle ; passez donc un « maintenant » fixe dans votre test.

## Node.js

```js theme={null}
import crypto from 'node:crypto';

const TOLERANCE_SECONDS = 300;

export function verifyQwairySignature({ rawBody, timestamp, signatureHeader, secret, now = Date.now() / 1000 }) {
  if (!/^\d+$/.test(timestamp ?? '')) return false;
  if (Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) return false;

  const expected = Buffer.from(
    'sha256=' +
      crypto
        .createHmac('sha256', secret)
        .update(timestamp + '.')
        .update(rawBody)
        .digest('hex'),
  );

  // Right after a rotation the header holds two comma-separated values.
  return (signatureHeader ?? '').split(',').some((candidate) => {
    const received = Buffer.from(candidate.trim());
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}
```

Utilisez-la avec un parseur de corps brut, par exemple dans Express :

```js theme={null}
import express from 'express';

const app = express();

app.post('/qwairy/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const valid = verifyQwairySignature({
    rawBody: req.body, // a Buffer, because of express.raw
    timestamp: req.get('X-Qwairy-Timestamp'),
    signatureHeader: req.get('X-Qwairy-Signature'),
    secret: process.env.QWAIRY_WEBHOOK_SECRET,
  });
  if (!valid) return res.status(401).end();

  const event = JSON.parse(req.body.toString('utf8'));
  // Deduplicate on event.id, queue the work, then answer quickly.
  res.status(204).end();
});
```

## Python

```python theme={null}
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify_qwairy_signature(raw_body: bytes, timestamp: str, signature_header: str, secret: bytes, now=None) -> bool:
    if not timestamp or not timestamp.isascii() or not timestamp.isdigit():
        return False
    now = time.time() if now is None else now
    if abs(now - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    expected = "sha256=" + hmac.new(
        secret, timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()

    # Right after a rotation the header holds two comma-separated values.
    return any(
        hmac.compare_digest(candidate.strip().encode(), expected.encode())
        for candidate in (signature_header or "").split(",")
    )
```

Utilisez-la avec le corps brut, par exemple dans Flask :

```python theme={null}
import os

from flask import Flask, request

app = Flask(__name__)


@app.post("/qwairy/webhooks")
def qwairy_webhook():
    valid = verify_qwairy_signature(
        raw_body=request.get_data(),  # the unparsed bytes
        timestamp=request.headers.get("X-Qwairy-Timestamp", ""),
        signature_header=request.headers.get("X-Qwairy-Signature", ""),
        secret=os.environ["QWAIRY_WEBHOOK_SECRET"].encode(),
    )
    if not valid:
        return "", 401

    event = request.get_json()
    # Deduplicate on event["id"], queue the work, then answer quickly.
    return "", 204
```

## Renouveler le secret

Après [Renouveler le secret de signature](https://docs.qwairy.co/fr/developers/endpoints/webhooks/rotate-secret.md), l’en-tête `X-Qwairy-Signature` porte **deux** valeurs séparées par une virgule pendant 24 heures. La première est signée avec le nouveau secret et la seconde avec l’ancien :

```text theme={null}
X-Qwairy-Signature: sha256=<signed with the new secret>,sha256=<signed with the previous secret>
```

Les deux exemples ci-dessus découpent l’en-tête et acceptent la requête dès qu’une valeur correspond au secret que vous détenez. Pour renouveler le secret sans perdre d’événements :

1. Renouvelez le secret et conservez la nouvelle valeur.
2. Déployez le nouveau secret sur votre récepteur. Les requêtes continuent de passer pendant la période de chevauchement, quel que soit le secret que vous détenez.
3. Après 24 heures, les requêtes portent de nouveau une seule signature.

`previousSecretExpiresAt` dans l’[endpoint](https://docs.qwairy.co/fr/developers/endpoints/webhooks/get.md) indique la fin du chevauchement.

## Dépannage

* **Toutes les requêtes échouent.** Vérifiez que vous signez le corps brut et non un corps resérialisé, et qu’aucun middleware ne le modifie avant votre gestionnaire.
* **Seules certaines requêtes échouent.** Vérifiez l’horloge de votre serveur par rapport à la tolérance de 5 minutes.
* **Une requête échoue après un renouvellement.** Vérifiez que vous utilisez le nouveau secret et que vous comparez chaque valeur de l’en-tête.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.