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

# Webhooks d’intégration

> Recevez des événements JSON signés quand un run, un audit ou une génération de prompts se termine, avec nouvelles tentatives, journal de 30 jours et renvoi.

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](https://docs.qwairy.co/fr/developers/endpoints/webhooks/list.md).

> [!NOTE]
>
> Les webhooks d’intégration sont distincts des [webhooks sortants](https://docs.qwairy.co/fr/developers/webhooks.md) 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](https://docs.qwairy.co/fr/developers/writing-data.md).

## Configurer un endpoint

**1. Créer l’endpoint**

Appelez [Créer un endpoint de webhook](https://docs.qwairy.co/fr/developers/endpoints/webhooks/create.md) avec votre URL HTTPS publique et les [événements](https://docs.qwairy.co/fr/developers/integration-webhooks/events.md) 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](https://docs.qwairy.co/fr/developers/integration-webhooks/verify-signatures.md), 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](https://docs.qwairy.co/fr/developers/endpoints/webhooks/test.md), puis lisez le résultat dans [Lister les envois](https://docs.qwairy.co/fr/developers/endpoints/webhooks/deliveries.md).

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](https://docs.qwairy.co/fr/developers/integration-webhooks/events.md#enveloppe) est la même pour chaque événement, et `data` dépend de l’événement.

| En-tête | Valeur |
| - | - |
| `X-Qwairy-Event` | Type d’événement, identique à `event` dans le corps |
| `X-Qwairy-Timestamp` | Heure Unix en secondes à laquelle cette tentative a été signée |
| `X-Qwairy-Delivery` | Identifiant de l’envoi, stable sur toutes les tentatives d’un même envoi |
| `X-Qwairy-Signature` | `sha256=` suivi du HMAC-SHA256 hexadécimal de la requête |

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 :

| Tentative | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
| - | - | - | - | - | - | - | - | - |
| Délai | 0 | 1 min | 5 min | 30 min | 2 h | 6 h | 12 h | 24 h |

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](https://docs.qwairy.co/fr/developers/endpoints/webhooks/update.md). 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](https://docs.qwairy.co/fr/developers/endpoints/webhooks/deliveries.md). Pour récupérer un événement manqué, [renvoyez](https://docs.qwairy.co/fr/developers/endpoints/webhooks/redeliver.md) 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

| Tâche | Référence |
| - | - |
| Lister les endpoints | [Lister les endpoints de webhook](https://docs.qwairy.co/fr/developers/endpoints/webhooks/list.md) |
| Créer un endpoint | [Créer un endpoint de webhook](https://docs.qwairy.co/fr/developers/endpoints/webhooks/create.md) |
| Lire un endpoint | [Obtenir un endpoint de webhook](https://docs.qwairy.co/fr/developers/endpoints/webhooks/get.md) |
| Modifier ou mettre en pause un endpoint | [Mettre à jour un endpoint de webhook](https://docs.qwairy.co/fr/developers/endpoints/webhooks/update.md) |
| Supprimer un endpoint | [Supprimer un endpoint de webhook](https://docs.qwairy.co/fr/developers/endpoints/webhooks/delete.md) |
| Changer le secret | [Renouveler le secret de signature](https://docs.qwairy.co/fr/developers/endpoints/webhooks/rotate-secret.md) |
| Vérifier votre récepteur | [Envoyer un événement de test](https://docs.qwairy.co/fr/developers/endpoints/webhooks/test.md) |
| Examiner les tentatives | [Lister les envois](https://docs.qwairy.co/fr/developers/endpoints/webhooks/deliveries.md) |
| Rejouer un événement | [Renvoyer un événement](https://docs.qwairy.co/fr/developers/endpoints/webhooks/redeliver.md) |


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