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

# Webhooks

> Recevez des notifications HTTP en temps réel lorsque des événements se produisent dans votre locataire Truthlocks.

Les webhooks permettent à votre application de recevoir des notifications automatiques lorsque des événements se produisent dans votre compte Truthlocks — par exemple, lorsqu'une attestation est émise, une clé est renouvelée ou une vérification échoue. Au lieu d'interroger l'API pour les changements, votre serveur reçoit une requête HTTP POST avec les détails de l'événement.

## Comment ça marche

**1. Enregistrer un point de terminaison**

Ajoutez un point de terminaison de webhook dans **Paramètres > Webhooks** dans la [console du locataire](https://console.truthlocks.com). Fournissez une URL HTTPS accessible publiquement et choisissez les types d'événements que vous souhaitez recevoir.

**2. Recevoir des événements**

Lorsqu'un événement correspondant se produit, Truthlocks envoie une requête HTTP POST à votre URL avec une charge utile JSON décrivant l'événement.

**3. Vérifier la signature**

Chaque requête inclut une signature HMAC-SHA256 dans l'en-tête `X-Truthlocks-Signature`. Vérifiez-la en utilisant le secret du point de terminaison pour confirmer que la requête provient de Truthlocks.

**4. Répondre avec 200**

Retournez un code de statut HTTP `200` pour accuser réception. Si votre point de terminaison échoue ou expire, Truthlocks réessaie avec un délai d'attente exponentiel.

## Types d'événements

Les événements sont regroupés en catégories. Vous pouvez vous abonner à des événements individuels ou utiliser un caractère générique (`attestation.*`) pour recevoir tous les événements d'une catégorie.

| Catégorie | Événement | Déclencheur |
| :- | :- | :- |
| **Attestations** | `attestation.created` | Une nouvelle attestation est créée |
| | `attestation.revoked` | Une attestation est révoquée |
| | `attestation.expired` | Une attestation atteint sa date d'expiration |
| | `attestation.superseded` | Une attestation est remplacée par une version plus récente |
| **Vérification** | `verification.completed` | Une vérification réussit |
| | `verification.failed` | Une vérification échoue |
| **Émetteurs** | `issuer.created` | Un nouvel émetteur est enregistré |
| | `issuer.updated` | Le profil ou les paramètres d'un émetteur changent |
| | `issuer.suspended` | Un émetteur est suspendu |
| **Clés** | `key.created` | Une clé de signature est enregistrée |
| | `key.rotated` | Une clé de signature est renouvelée |
| | `key.revoked` | Une clé de signature est révoquée |
| | `key.compromised` | Une clé est signalée comme compromise |
| **Équipe** | `team.member_invited` | Une invitation d'équipe est envoyée |
| | `team.member_joined` | Un membre de l'équipe accepte une invitation |
| | `team.member_removed` | Un membre de l'équipe est supprimé |
| | `team.role_changed` | Le rôle d'un membre de l'équipe est mis à jour |
| **Facturation** | `billing.subscription.created` | Un nouvel abonnement est créé |
| | `billing.subscription.updated` | Un abonnement est modifié |
| | `billing.invoice.created` | Une nouvelle facture est générée |
| | `billing.usage.threshold` | Un seuil d'utilisation est atteint |
| **Consommateur** | `consumer.content.protected` | Un consommateur protège un nouveau contenu |
| **Signaux de risque** | `risk.signal.created` | Un signal de risque est ingéré (tout chemin de détection) |
| | `risk.signal.escalated` | Un score de signal de risque dépasse le seuil de révision automatique |
| **Reçus** | `receipt.created` | Un nouveau reçu est créé |
| | `receipt.revoked` | Un reçu est révoqué |
| | `receipt.type.created` | Un nouveau type de reçu est créé |
| | `receipt.type.deprecated` | Un type de reçu est obsolète |
| **Sécurité** | `security.password_changed` | Un utilisateur change son mot de passe |
| | `security.api_key_compromised` | Une clé API est signalée comme compromise |
| | `security.suspicious_activity` | Une activité de compte suspecte est détectée |

### Filtres génériques

Utilisez `category.*` pour vous abonner à chaque événement d'une catégorie. Par exemple, `attestation.*` correspond à `attestation.created`, `attestation.revoked`, `attestation.expired` et `attestation.superseded`.

## Limites des points de terminaison par plan

Le nombre de points de terminaison de webhook que vous pouvez créer dépend de votre niveau de plan :

| Plan | Limite de points de terminaison |
| :- | :- |
| Gratuit | 1 |
| Starter | 3 |
| Entreprise | 10 |
| Entreprise | 25 |

Besoin de plus de points de terminaison ? Contactez votre responsable de compte ou mettez à niveau votre plan dans **Paramètres > Facturation**.

## Création d'un point de terminaison

1. Dans la console du locataire, allez dans **Paramètres > Webhooks**.
2. Cliquez sur **Ajouter un point de terminaison**.
3. Entrez un nom, votre URL de destination HTTPS, et sélectionnez les types d'événements que vous souhaitez recevoir.
4. Cliquez sur **Créer**.

La console affiche votre secret de point de terminaison une seule fois. Copiez-le immédiatement — vous ne pourrez pas le récupérer plus tard.

### Via l'API

```http Request theme={null}
POST /v1/webhooks/endpoints
X-API-Key: tl_live_...
Content-Type: application/json

{
  "name": "My Backend",
  "url": "https://api.example.com/webhooks/truthlock",
  "event_filters": ["attestation.*", "verification.completed"]
}
```

```json Response theme={null}
{
  "id": "ep_abc123",
  "name": "My Backend",
  "url": "https://api.example.com/webhooks/truthlock",
  "status": "active",
  "secret": "whsec_...",
  "event_filters": ["attestation.*", "verification.completed"],
  "created_at": "2026-03-25T12:00:00Z"
}
```

### Lister les points de terminaison

Récupère tous les points de terminaison de webhook pour votre locataire :

```http Request theme={null}
GET /v1/webhooks/endpoints
X-API-Key: tl_live_...
```

Consultez la [référence complète de l'API](https://docs.truthlocks.com/fr/api-reference/webhooks/list-endpoints.md) pour les détails de la réponse.

## Vérification des signatures

Chaque requête de webhook inclut un en-tête de signature pour vérification. Vérifiez toujours les signatures avant de traiter les événements.

**Format de signature :**

```
X-Truthlocks-Signature: t=1710000000,v1=a1b2c3d4e5f6...
```

Où `t` est l'horodatage Unix et `v1` est le condensé hexadécimal HMAC-SHA256.

**Étapes de vérification :**

1. Extrayez `t` (horodatage) et `v1` (signature) de l'en-tête.
2. Rejetez la requête si l'horodatage est antérieur de plus de 5 minutes.
3. Concaténez `{timestamp}.{raw_request_body}` pour former la chaîne de signature.
4. Calculez le HMAC-SHA256 de la chaîne de signature en utilisant le secret de votre point de terminaison.
5. Comparez le digest calculé à `v1` en utilisant une comparaison à temps constant.

```typescript verify-webhook.ts theme={null}
import crypto from "crypto";
import express from "express";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/truthlock", (req, res) => {
  const sigHeader = req.headers["x-truthlocks-signature"] as string;
  if (!sigHeader) return res.status(401).send("Missing signature");

  const parts = Object.fromEntries(
    sigHeader.split(",").map((p) => p.split("=") as [string, string])
  );
  const timestamp = parts["t"];
  const signature = parts["v1"];

  // Reject stale requests (5-minute window)
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > 300) return res.status(401).send("Timestamp expired");

  // Compute expected signature
  const signingString = `${timestamp}.${req.body.toString()}`;
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
    .update(signingString)
    .digest("hex");

  // Constant-time comparison
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body.toString());
  console.log("Received event:", event.type);

  res.status(200).json({ received: true });
});
```

```go verify-webhook.go theme={null}
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"math"
	"net/http"
	"strconv"
	"strings"
	"time"
)

func verifyWebhook(r *http.Request, secret string) ([]byte, error) {
	sig := r.Header.Get("X-Truthlocks-Signature")
	if sig == "" {
		return nil, fmt.Errorf("missing signature header")
	}

	parts := map[string]string{}
	for _, p := range strings.Split(sig, ",") {
		kv := strings.SplitN(p, "=", 2)
		if len(kv) == 2 {
			parts[kv[0]] = kv[1]
		}
	}

	ts, _ := strconv.ParseInt(parts["t"], 10, 64)
	age := math.Abs(float64(time.Now().Unix() - ts))
	if age > 300 {
		return nil, fmt.Errorf("timestamp expired")
	}

	body, err := io.ReadAll(r.Body)
	if err != nil {
		return nil, err
	}

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(fmt.Sprintf("%d.%s", ts, body)))
	expected := hex.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(parts["v1"]), []byte(expected)) {
		return nil, fmt.Errorf("invalid signature")
	}

	return body, nil
}
```

```python verify_webhook.py theme={null}
import hashlib
import hmac
import time
from flask import Flask, request, abort

app = Flask(__name__)

@app.route("/webhooks/truthlock", methods=["POST"])
def handle_webhook():
    sig_header = request.headers.get("X-Truthlocks-Signature", "")
    parts = dict(p.split("=", 1) for p in sig_header.split(","))

    timestamp = parts.get("t", "")
    signature = parts.get("v1", "")

    # Reject stale requests
    if abs(time.time() - int(timestamp)) > 300:
        abort(401, "Timestamp expired")

    # Compute expected signature
    signing_string = f"{timestamp}.{request.get_data(as_text=True)}"
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        signing_string.encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401, "Invalid signature")

    event = request.get_json()
    print(f"Received event: {event['type']}")
    return {"received": True}
```

> [!WARNING]
>
> Utilisez toujours une fonction de comparaison à temps constant (comme `crypto.timingSafeEqual` ou `hmac.compare_digest`) pour prévenir les attaques par synchronisation.

## En-têtes de requête

Chaque livraison de webhook inclut ces en-têtes :

| En-tête | Description |
| :- | :- |
| `Content-Type` | `application/json` |
| `User-Agent` | `Truthlocks-Webhook-Service/1.0` |
| `X-Truthlocks-Event-Id` | Identifiant unique de l'événement |
| `X-Truthlocks-Event-Type` | Type d'événement (par exemple, `attestation.created`) |
| `X-Truthlocks-Timestamp` | Horodatage Unix de la tentative de livraison |
| `X-Truthlocks-Signature` | Signature HMAC-SHA256 pour vérification |

## Comportement de nouvelle tentative

Si votre point de terminaison renvoie un code de statut non-2xx ou ne répond pas dans les 5 secondes, Truthlocks réessaie la livraison avec un délai d'attente exponentiel :

| Tentative | Délai approximatif |
| :- | :- |
| 1ère tentative | \~1 seconde |
| 2ème tentative | \~2 secondes |
| 3ème tentative | \~4 secondes |
| 4e tentative | \~16 secondes |
| 5e tentative | \~1 minute |
| 6e tentative | \~2 minutes |
| 7e tentative | \~5 minutes (max) |

Les délais incluent jusqu'à 30 % de gigue. Après 8 tentatives au total (1 initiale + 7 nouvelles tentatives), la livraison est marquée comme échouée.

Vous pouvez consulter les tentatives de livraison et les détails des échecs dans **Paramètres > Webhooks** en cliquant sur un point de terminaison, ou les interroger via l'API :

```http Request theme={null}
GET /v1/webhooks/endpoints/{id}/deliveries
X-API-Key: tl_live_...
```

Consultez la [référence de l'API de liste des livraisons](https://docs.truthlocks.com/fr/api-reference/webhooks/list-deliveries.md) pour les détails de la réponse.

## Rotation des secrets

Si votre secret de webhook est compromis, faites-le pivoter immédiatement :

1. Dans la console du locataire, allez dans **Paramètres > Webhooks** et cliquez sur le point de terminaison.
2. Cliquez sur **Faire pivoter le secret**.
3. Copiez le nouveau secret — l'ancien secret cesse de fonctionner immédiatement.

Vous pouvez également effectuer une rotation via l'API :

```http Request theme={null}
POST /v1/webhooks/endpoints/{id}/rotate
X-API-Key: tl_live_...
```

## Tester les webhooks

Envoyez un événement de test pour vérifier que votre point de terminaison fonctionne :

1. Dans la console du locataire, allez dans **Paramètres > Webhooks** et cliquez sur le point de terminaison.
2. Cliquez sur **Envoyer le test**.
3. Un événement `webhook.test` est envoyé à votre URL en utilisant le pipeline complet de signature et de livraison.

Via l'API :

```http Request theme={null}
POST /v1/webhooks/test-delivery
X-API-Key: tl_live_...
Content-Type: application/json

{
  "endpoint_id": "ep_abc123",
  "event_type": "webhook.test",
  "payload": { "status": "ok", "source": "test-delivery" }
}
```

Les champs `event_type` et `payload` sont facultatifs — ils sont par défaut `webhook.test` et une charge utile de statut de base s'ils sont omis.

## Notifications de signaux de risque

Vous pouvez recevoir des notifications webhook en temps réel chaque fois qu'un signal de risque est créé par l'un des cinq chemins de détection du [pare-feu d'identité anti-fraude](https://docs.truthlocks.com/fr/guides/risk-signals.md) — ingestion directe, normalisation d'événements, analyse de deepfake, détection d'ATO et score de vélocité.

Abonnez-vous à `risk.signal.*` pour recevoir tous les événements de signal de risque, ou abonnez-vous à `risk.signal.created` ou `risk.signal.escalated` individuellement.

### Charge utile d'exemple

```json theme={null}
{
  "id": "evt_r1s2k3...",
  "type": "risk.signal.created",
  "created_at": "2027-07-24T09:15:00Z",
  "data": {
    "signal_id": "a1b2c3d4-...",
    "signal_source": "velocity",
    "signal_type": "velocity",
    "risk_score": 72,
    "subject_type": "user",
    "subject_id": "usr_8f14e45f"
  }
}
```

### Répondre aux signaux de risque

Utilisez les webhooks de signal de risque pour déclencher des réponses automatisées — bloquer une session utilisateur, notifier votre équipe de sécurité ou escalader vers un cas de fraude — sans interroger l'API.

```javascript theme={null}
app.post("/webhooks/truthlock", (req, res) => {
  const event = JSON.parse(req.body.toString());

  if (event.type === "risk.signal.created") {
    const { risk_score, subject_id, signal_type } = event.data;

    if (risk_score >= 80) {
      // Critical — block immediately and alert security
      blockSubject(subject_id);
      notifySecurityTeam(event.data);
    } else if (risk_score >= 60) {
      // High — throttle and log for review
      throttleSubject(subject_id);
    }
  }

  res.status(200).json({ received: true });
});
```

> [!NOTE]
>
> Les webhooks de signal de risque se déclenchent pour les signaux créés par les cinq chemins de détection. Le champ `signal_source` dans la charge utile vous indique quel chemin a généré le signal — `external`, `event_normalization`, `deepfake`, `ato`, ou `velocity`.

## Bonnes pratiques

> [!TIP]
>
> Répondez rapidement aux webhooks. Effectuez votre traitement lourd de manière asynchrone après avoir renvoyé une réponse `200` pour éviter les délais d'attente et les tentatives.

* **Vérifiez chaque signature.** Ne sautez jamais la vérification de signature, même en développement.
* **Utilisez une file d'attente de messages.** Mettez en file d'attente les événements entrants et traitez-les dans un travailleur pour éviter de bloquer la réponse HTTP.
* **Gérer les doublons.** Utilisez l'en-tête `X-Truthlocks-Event-Id` pour dédupliquer les événements en cas de nouvelles tentatives.
* **Surveiller les échecs de livraison.** Vérifiez régulièrement l'onglet des livraisons dans la console pour les livraisons échouées ou mortes.
* **Gardez les secrets en sécurité.** Stockez votre secret de webhook dans des variables d'environnement, pas dans le code source.


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