Passer au contenu principal
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. 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.

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 : 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

Request
Response

Lister les points de terminaison

Récupère tous les points de terminaison de webhook pour votre locataire :
Request
Consultez la référence complète de l’API 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 :
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.
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 :

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 : 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 :
Request
Consultez la référence de l’API de liste des livraisons 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 :
Request

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 :
Request
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 — 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

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

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.