Un webhook est une URL sur votre serveur que nous appelons quand quelque chose se produit, par exemple quand une question a obtenu toutes ses réponses. Votre code n’a pas à interroger sans cesse.

En configurer un

  1. Dans Développeurs, choisissez Webhooks, puis ajoutez un endpoint.
  2. Saisissez une URL HTTPS et choisissez les événements voulus, par exemple question.completed.
  3. Copiez le secret de signature. Il ne s’affiche qu’une fois.
  4. Envoyez un test pour vérifier que votre serveur le reçoit et que la signature est valide.

Vous pouvez aussi gérer les endpoints depuis votre code : voir la dernière section ci-dessous.

Événements

Questions réservées, terminées, incomplètes, annulées ou refusées ; crédits achetés, qui s’épuisent ou qui expirent ; contestations résolues ; et connexion proche de son plafond. Un test que vous envoyez arrive sous le nom webhook.test. Pour agir sur ces événements sans serveur, utilisez l’app Zapier.

Chaque endpoint garde la version de contenu avec laquelle il a été créé. Dans une version, nous ne faisons qu’ajouter des champs ; nous n’en supprimons ni n’en modifions jamais. La documentation des webhooks (en anglais) renvoie aux champs exacts de chaque événement.

Webhooks d’équipe

Un endpoint appartient au compte dans lequel vous l’avez créé. Créé pendant que vous travaillez dans une équipe, il reçoit les événements des questions de tous les membres de cette équipe, ainsi que ceux des crédits de l’équipe. La personne qui a posé la question reçoit aussi l’événement sur ses propres endpoints.

Dans une équipe, le propriétaire et les admins peuvent ajouter, modifier et supprimer des endpoints. Les membres peuvent les voir, avec leurs envois.

Seulement certaines questions

Vous pouvez donner un filtre à un endpoint, pour qu’il ne reçoive les événements de questions que pour certains projets ou libellés. Les événements qui ne concernent pas une question, comme des crédits qui s’épuisent, arrivent toujours.

Vérifier la signature

Chaque envoi est signé avec votre secret de deux façons ; vérifiez celle qui vous convient :

  • les en-têtes webhook-id, webhook-timestamp et webhook-signature de Standard Webhooks, que de nombreuses bibliothèques de webhooks vérifient pour vous ;
  • notre en-tête x-50heads-signature, avec un horodatage et un HMAC-SHA256 du corps.

Vérifiez l’une des deux avant de vous fier au contenu. La documentation des webhooks (en anglais) propose du code à copier en TypeScript, Python et Go.

Si votre secret date d’avant le 10 octobre 2026 et que vous utilisez une bibliothèque Standard Webhooks, renouvelez le secret une fois pour que la bibliothèque l’accepte.

Changer le secret

Le renouvellement vous donne un nouveau secret, affiché une seule fois. L’ancien continue de fonctionner à côté pendant 24 heures, sauf si vous choisissez une autre durée, jusqu’à 7 jours. Pendant ce temps, chaque envoi est signé avec les deux : rien n’échoue pendant que vous mettez votre serveur à jour.

Si vous pensez qu’un secret a fuité, renouvelez-le sans chevauchement. L’ancien secret s’arrête aussitôt.

Nouvelles tentatives et renvoi

Répondez avec un statut 2xx en moins de dix secondes. Sinon, nous réessayons avec un délai croissant, huit fois sur environ 24 heures. Le journal Envois montre chaque tentative, et vous pouvez rejouer n’importe quel envoi.

Il arrive qu’un envoi arrive deux fois ou dans le désordre. Utilisez l’identifiant de l’événement pour ignorer les doublons.

Si cinq envois de suite échouent après toutes les tentatives, nous désactivons l’endpoint et vous prévenons par e-mail. L’e-mail renvoie vers l’endpoint sous Webhooks, dans Développeurs. Il y apparaît comme Désactivé, avec la date et la raison. Une fois votre serveur réparé, choisissez Reprendre, puis rejouez les envois manqués. Rien n’est envoyé à un endpoint tant qu’il est désactivé.

Vous pouvez aussi choisir Mettre en pause sur n’importe quel endpoint pour arrêter les envois un moment. Il apparaît alors comme désactivé de la même façon, et Reprendre le relance. Seuls le propriétaire ou un admin peuvent mettre en pause ou reprendre l’endpoint d’une équipe.

Gérer les webhooks depuis votre code

Une clé, ou un assistant IA que vous avez connecté, peut lister, ajouter, modifier, tester et rejouer des endpoints s’il a ces permissions :

  • webhooks:read : voir les endpoints et leurs envois.
  • webhooks:write : ajouter, modifier, renouveler le secret, tester, rejouer et supprimer des endpoints.

Elles ne sont jamais accordées d’office, car elles décident où les événements de vos questions sont envoyés. Cochez-les quand vous créez une clé. Une application doit les demander, et vous les voyez listées avant de l’autoriser. Les clés créées avant l’arrivée des permissions ne peuvent pas gérer les webhooks : créez une nouvelle clé. La documentation des webhooks (en anglais) donne les détails.