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

# Événements des webhooks d’intégration

> Référence des neuf événements de webhook d’intégration : quand chacun est envoyé, les champs de son objet data et un exemple de charge utile pour chacun.

Chaque requête de webhook d’intégration a la même enveloppe. L’objet `data` dépend de l’événement. Considérez les charges utiles comme compatibles avec les évolutions futures : ignorez les champs que vous n’utilisez pas au lieu de rejeter la requête. La livraison se fait au moins une fois et sans ordre garanti ; [dédupliquez donc sur `id`](https://docs.qwairy.co/fr/developers/integration-webhooks/overview#garanties-de-livraison).

## Enveloppe

| Champ | Type | Signification |
| - | - | - |
| `id` | string | Identifiant de l’événement, stable entre les tentatives et les renvois |
| `event` | string | Type d’événement |
| `createdAt` | string | Date de l’événement au format ISO 8601 |
| `teamId` | string | Identifiant de l’équipe |
| `brandId` | string ou null | Identifiant du workspace, ou `null` pour les événements au niveau de l’équipe |
| `data` | object | Champs propres à l’événement |

Les événements ne contiennent ni texte de prompt ou de réponse, ni sources citées, ni adresses email, ni noms de personnes, ni identifiants Stripe.

| Événement | Envoyé lorsque |
| - | - |
| [`run.completed`](#run-completed) | Un run s’est terminé avec succès |
| [`run.failed`](#run-failed) | Un run a échoué |
| [`run.cancelled`](#run-cancelled) | Un run a été annulé |
| [`pitch_audit.completed`](#pitch_audit-completed) | Le rapport d’un audit de prospection est prêt |
| [`pitch_audit.failed`](#pitch_audit-failed) | Un audit de prospection a échoué |
| [`site_audit.completed`](#site_audit-completed) | Toutes les pages d’un audit de pages sont terminées |
| [`prompt_suggestions.ready`](#prompt_suggestions-ready) | Une génération de suggestions de prompts s’est terminée |
| [`prompt_suggestions.failed`](#prompt_suggestions-failed) | Une génération de suggestions de prompts a échoué |
| [`webhook.test`](#webhook-test) | Vous avez envoyé un événement de test |

Tous les horodatages des exemples sont synthétiques.

## `run.completed`

Un run a atteint un état final réussi, qu’il soit manuel ou planifié. `brandId` est le workspace du run.

Les événements de run sont envoyés dès qu’un run ne peut plus changer. Tant qu’un run contient une réponse en quarantaine dont la charge utile du fournisseur peut encore être rejouée, pendant 7 jours au plus, son événement attend. Pendant ce temps, [Lister les runs](https://docs.qwairy.co/fr/developers/endpoints/runs/list.md) peut déjà indiquer le run comme terminé. Cela vaut aussi pour `run.failed` et `run.cancelled`.

| Champ | Type | Signification |
| - | - | - |
| `runId` | string | Identifiant du run, comme dans [Obtenir un run](https://docs.qwairy.co/fr/developers/endpoints/runs/get.md) |
| `purpose` | string | `PERIODIC`, `PROMPT_ADDED`, `MANUAL` ou `ONBOARDING` |
| `status` | string | `COMPLETED`, `COMPLETED_WITH_WARNINGS` ou `NO_WORK` |
| `counts` | object | Nombres d’éléments `requested`, `completed`, `failed`, `skipped` et `cancelled` |
| `creditsDebited` | integer | Crédits débités pour ce traitement |
| `createdAt` | string | Date de création du run au format ISO 8601 |
| `finalizedAt` | string | Date à laquelle le run a atteint son état final, au format ISO 8601 |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "run.completed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "runId": "run_synthetic_01",
    "purpose": "MANUAL",
    "status": "COMPLETED_WITH_WARNINGS",
    "counts": { "requested": 40, "completed": 38, "failed": 2, "skipped": 0, "cancelled": 0 },
    "creditsDebited": 76,
    "createdAt": "2026-11-02T09:02:11Z",
    "finalizedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `run.failed`

Un run a échoué, y compris par un échec de planification. `brandId` est le workspace du run.

| Champ | Type | Signification |
| - | - | - |
| `runId` | string | Identifiant du run, comme dans [Obtenir un run](https://docs.qwairy.co/fr/developers/endpoints/runs/get.md) |
| `purpose` | string | `PERIODIC`, `PROMPT_ADDED`, `MANUAL` ou `ONBOARDING` |
| `status` | string | `FAILED` |
| `counts` | object | Nombres d’éléments `requested`, `completed`, `failed`, `skipped` et `cancelled` |
| `creditsDebited` | integer | Crédits débités pour ce traitement |
| `createdAt` | string | Date de création du run au format ISO 8601 |
| `finalizedAt` | string | Date à laquelle le run a atteint son état final, au format ISO 8601 |
| `errorCode` | string | `RUN_PLANNING_FAILED` ou `RUN_ALL_ITEMS_FAILED`, sans sortie de fournisseur ni texte client |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "run.failed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "runId": "run_synthetic_01",
    "purpose": "MANUAL",
    "status": "FAILED",
    "counts": { "requested": 40, "completed": 0, "failed": 0, "skipped": 0, "cancelled": 0 },
    "creditsDebited": 0,
    "createdAt": "2026-11-02T09:02:11Z",
    "finalizedAt": "2026-11-02T09:14:07Z",
    "errorCode": "RUN_PLANNING_FAILED"
  }
}
```

## `run.cancelled`

Un run a été annulé. `brandId` est le workspace du run.

| Champ | Type | Signification |
| - | - | - |
| `runId` | string | Identifiant du run, comme dans [Obtenir un run](https://docs.qwairy.co/fr/developers/endpoints/runs/get.md) |
| `purpose` | string | `PERIODIC`, `PROMPT_ADDED`, `MANUAL` ou `ONBOARDING` |
| `status` | string | `CANCELLED` |
| `counts` | object | Nombres d’éléments `requested`, `completed`, `failed`, `skipped` et `cancelled` |
| `creditsDebited` | integer | Crédits débités pour ce traitement |
| `createdAt` | string | Date de création du run au format ISO 8601 |
| `finalizedAt` | string | Date à laquelle le run a atteint son état final, au format ISO 8601 |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "run.cancelled",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "runId": "run_synthetic_01",
    "purpose": "MANUAL",
    "status": "CANCELLED",
    "counts": { "requested": 40, "completed": 12, "failed": 0, "skipped": 0, "cancelled": 28 },
    "creditsDebited": 24,
    "createdAt": "2026-11-02T09:02:11Z",
    "finalizedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `pitch_audit.completed`

Le rapport d’un audit de prospection est prêt. Les audits de prospection appartiennent à l’équipe ; `brandId` vaut donc `null`.

| Champ | Type | Signification |
| - | - | - |
| `auditId` | string | Identifiant de l’audit de prospection, comme dans [Obtenir un audit de prospection](https://docs.qwairy.co/fr/developers/endpoints/pitch-audits/get.md) |
| `subjects` | integer | Nombre de sujets audités |
| `creditsDebited` | integer | Crédits débités pour ce traitement |
| `completedAt` | string | Date de fin au format ISO 8601 |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "pitch_audit.completed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": null,
  "data": {
    "auditId": "audit_synthetic_01",
    "subjects": 3,
    "creditsDebited": 120,
    "completedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `pitch_audit.failed`

Un audit de prospection a échoué définitivement. `brandId` vaut `null`.

| Champ | Type | Signification |
| - | - | - |
| `auditId` | string | Identifiant de l’audit de prospection |
| `errorCode` | string | `PITCH_AUDIT_FAILED` ou `PITCH_AUDIT_PROMPT_PREPARATION_FAILED`, sans sortie de fournisseur ni texte client |
| `failedAt` | string | Date d’échec au format ISO 8601 |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "pitch_audit.failed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": null,
  "data": {
    "auditId": "audit_synthetic_01",
    "errorCode": "PITCH_AUDIT_FAILED",
    "failedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `site_audit.completed`

Toutes les pages d’un audit de pages sont terminées. `brandId` est le workspace de l’audit.

| Champ | Type | Signification |
| - | - | - |
| `auditId` | string | Identifiant de l’audit, l’`id` de [Obtenir un audit de pages](https://docs.qwairy.co/fr/developers/endpoints/site-diagnostics/get-audit.md) |
| `counts` | object | Nombres de pages `total`, `succeeded`, `failed` et `skipped` |
| `createdAt` | string | Date de création au format ISO 8601 |
| `completedAt` | string | Date de fin de l’audit au format ISO 8601 : le dernier résultat de page, pages ignorées comprises, ou la clôture de la mise en file, selon la plus tardive. [Obtenir un audit de pages](https://docs.qwairy.co/fr/developers/endpoints/site-diagnostics/get-audit.md) renvoie la même valeur |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "site_audit.completed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "auditId": "site_audit_synthetic_01",
    "counts": { "total": 12, "succeeded": 11, "failed": 1, "skipped": 0 },
    "createdAt": "2026-11-02T09:02:11Z",
    "completedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `prompt_suggestions.ready`

Une génération de Prompt Studio s’est terminée. `brandId` est le workspace de la génération.

`recommendations` est la valeur que [Obtenir une génération de suggestions](https://docs.qwairy.co/fr/developers/endpoints/prompt-suggestions/get-run.md) renvoyait pour ce run au moment de l’enregistrement de l’événement. Une lecture ultérieure du run peut différer, car les prompts suivis, les concurrents et les générations plus récentes la font évoluer. Elle vaut null quand le run ne correspond à aucune recommandation : une préparation `profile`, un pool qui n’est plus le dernier pool utilisable, ou un topic supprimé. Seuls les runs de Prompt Studio des clients produisent ces événements, pas les outils publics de génération de prospects.

| Champ | Type | Signification |
| - | - | - |
| `runId` | string | Identifiant de la génération, l’`id` de [Obtenir une génération de suggestions](https://docs.qwairy.co/fr/developers/endpoints/prompt-suggestions/get-run.md) |
| `source` | string | `manual`, `onboarding`, `topic` ou `profile` |
| `keywordId` | string ou null | Topic de la génération, lorsqu’il y en a un |
| `recommendations` | integer ou null | Nombre de suggestions recommandées au moment de l’enregistrement de l’événement |
| `completedAt` | string | Date de fin au format ISO 8601 |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "prompt_suggestions.ready",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "runId": "suggestion_run_synthetic_01",
    "source": "manual",
    "keywordId": null,
    "recommendations": 20,
    "completedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `prompt_suggestions.failed`

Une génération de Prompt Studio a échoué. `brandId` est le workspace de la génération.

| Champ | Type | Signification |
| - | - | - |
| `runId` | string | Identifiant de la génération |
| `source` | string | `manual`, `onboarding`, `topic` ou `profile` |
| `keywordId` | string ou null | Topic de la génération, lorsqu’il y en a un |
| `failedAt` | string | Date d’échec au format ISO 8601 |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "prompt_suggestions.failed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "runId": "suggestion_run_synthetic_01",
    "source": "topic",
    "keywordId": "topic_synthetic_01",
    "failedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `webhook.test`

Envoyé uniquement par [Envoyer un événement de test](https://docs.qwairy.co/fr/developers/endpoints/webhooks/test.md), à un seul endpoint, même s’il est désactivé. `brandId` vaut `null`.

| Champ | Type | Signification |
| - | - | - |
| `message` | string | Un message de test fixe |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "webhook.test",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": null,
  "data": {
    "message": "Test event from Qwairy."
  }
}
```


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