Passer au contenu principal
Les webhooks d’intégration signalent à vos systèmes qu’un traitement est terminé, sans que vous ayez à interroger l’API. Qwairy envoie une requête POST JSON signée vers votre endpoint HTTPS lorsqu’un run, un audit de prospection, un audit de pages ou une génération de suggestions de prompts atteint un état final. Vous gérez les endpoints avec l’API REST.
Les webhooks d’intégration sont distincts des webhooks sortants des équipes en marque blanche, qui remplacent les emails de rapport hebdomadaire et d’export prêt. Ils utilisent d’autres endpoints, événements, charges utiles et réglages, et ne sont pas liés aux alertes. Configurer l’un ne modifie jamais l’autre.

Disponibilité

Les webhooks d’intégration sont disponibles avec les offres Business, Agency Business et Enterprise. Créer, modifier, renouveler et supprimer un endpoint sont des commandes d’API ; elles exigent donc aussi un jeton d’API dont l’accès en écriture est activé. Un Propriétaire ou un Manager l’active pour chaque jeton dans Gestion de l’équipe > API REST. Consultez Écrire des données.

Configurer un endpoint

1

Créer l’endpoint

Appelez Créer un endpoint de webhook avec votre URL HTTPS publique et les événements souhaités. Limitez-le à certains workspaces avec brandIds, ou laissez-le vide pour recevoir tous les workspaces de l’équipe.
2

Conserver le secret de signature

Le secret figure dans la réponse et ne peut plus être relu. Conservez-le dans un gestionnaire de secrets.
3

Vérifier les signatures

Vérifiez chaque requête comme décrit dans Vérifier les signatures, et rejetez les appels non signés ou mal signés. Chaque clé de l’équipe qui peut lire ses webhooks, clés en lecture seule comprises, reçoit l’URL complète de l’endpoint. Un jeton intégré à l’URL n’est donc pas un secret pour ces clés.
4

Envoyer un événement de test

Appelez Envoyer un événement de test, puis lisez le résultat dans Lister les envois.
Une équipe peut avoir 10 endpoints au maximum. Un endpoint ne reçoit que les événements survenus après sa création. La création des événements manqués est reprise toutes les dix minutes dans la fenêtre de 30 jours du journal ; la reprise n’inscrit pas un nouvel endpoint aux événements antérieurs. Le filtre brandIds s’applique uniquement aux événements des workspaces. Les événements d’audit de prospection au niveau de l’équipe auxquels l’endpoint est abonné sont livrés indépendamment de ce filtre.

Ce que Qwairy envoie

Chaque requête est un POST avec un corps JSON. L’enveloppe est la même pour chaque événement, et data dépend de l’événement. Les événements portent des identifiants, des statuts, des décomptes et des horodatages. Ils ne contiennent jamais de texte de prompt ou de réponse, de sources citées, d’adresses email, de noms de personnes ni d’identifiants Stripe. Lisez les détails dont vous avez besoin via l’API REST avec les identifiants de l’événement.

Garanties de livraison

  • La livraison se fait au moins une fois. Le même événement peut vous parvenir plusieurs fois.
  • L’ordre n’est pas garanti. Un événement plus récent peut arriver avant un événement plus ancien.
  • Dédupliquez sur l’id de l’événement. Il est identique entre les tentatives et les renvois.
  • Répondez avec n’importe quel statut 2xx en 10 secondes. Tout autre résultat est un échec.
  • Les redirections ne sont pas suivies. Enregistrez l’URL finale.
  • Répondez rapidement, puis traitez l’événement de façon asynchrone.

Nouvelles tentatives et désactivation automatique

Si une tentative échoue, Qwairy réessaie jusqu’à huit tentatives au total, à ces délais à partir du début du cycle de livraison : Pour un événement récupéré, le cycle commence à la mise en file de sa livraison, pas à la date d’origine de l’événement. Un renvoi manuel commence un nouveau cycle avec le même identifiant d’événement. Une livraison en retard sur ce calendrier, par exemple pendant une pause des livraisons ou pendant que l’endpoint était désactivé, conserve au moins l’écart entre deux tentatives consécutives après sa dernière tentative ; ses tentatives restantes ne s’enchaînent donc pas en quelques minutes. Les échecs ne désactivent un endpoint que lors d’une tentative échouée : une tentative qui échoue alors que la série d’échecs en cours a commencé au moins 72 heures plus tôt, sans livraison réussie depuis. Le temps seul ne désactive jamais un endpoint. Un endpoint qui ne reçoit aucune tentative, par exemple pendant une pause des livraisons ou lorsqu’aucun événement n’est dû, reste activé jusqu’à sa prochaine tentative échouée. Un endpoint ainsi désactivé a le disabledReason FAILING. Les Propriétaires de l’équipe reçoivent un email opérationnel dans les minutes qui suivent la désactivation de l’endpoint ; ce n’est pas une alerte. Un email qui ne peut pas être envoyé est relancé jusqu’à 7 jours après la désactivation de l’endpoint, puis abandonné. Corrigez votre récepteur, puis réactivez l’endpoint avec Mettre à jour un endpoint de webhook. La réactivation efface l’état d’échec et ouvre un nouvel épisode : une nouvelle série de 72 heures d’échecs peut de nouveau désactiver l’endpoint, et les Propriétaires reçoivent de nouveau un email.

Journal d’envoi et renvoi

Qwairy conserve le journal d’envoi pendant 30 jours. Lisez-le avec Lister les envois. Pour récupérer un événement manqué, renvoyez un envoi réussi, épuisé ou annulé des 30 derniers jours. L’événement renvoyé conserve son id d’origine. La conservation commence à la création de la livraison, y compris pour un événement récupéré. Un cycle de renvoi accepté est conservé pendant 30 jours à partir de son démarrage ; l’ancienneté de l’événement source ne raccourcit jamais ses nouvelles tentatives. La mise en pause conserve les livraisons en attente, mais arrête l’inscription aux nouveaux événements. Un événement de test peut toujours être envoyé. Supprimer un endpoint annule les livraisons en attente ; une requête HTTP déjà en cours peut encore arriver. Lorsqu’un workspace change d’équipe, son historique de livraison reste dans l’équipe d’origine, mais ses événements en attente sont annulés au contrôle de propriété précédant leur livraison.

Gérer les endpoints