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

# Créer un endpoint de webhook

> Enregistrez un endpoint HTTPS pour les événements de webhook d’intégration. Le secret de signature n’est renvoyé qu’une fois. Maximum de 10 endpoints.

Crée un endpoint pour l’équipe. Le secret de signature n’est renvoyé qu’**une fois**, dans cette réponse uniquement. Conservez-le pour [vérifier les signatures](https://docs.qwairy.co/fr/developers/integration-webhooks/verify-signatures.md). Une équipe peut avoir 10 endpoints au maximum.

Les webhooks d’intégration nécessitent une offre Business, Agency Business ou Enterprise active. Modifier un endpoint exige aussi un jeton d’API dont l’accès en écriture a été activé par un Propriétaire ou un Manager. Consultez [Webhooks d’intégration](https://docs.qwairy.co/fr/developers/integration-webhooks/overview.md) et [Écrire des données](https://docs.qwairy.co/fr/developers/writing-data.md).

**Authorization** `string` *required*

Jeton bearer de votre équipe.

**Idempotency-Key** `string` *required*

Clé unique pour cette opération, 255 caractères au maximum. Les réponses terminées sont rejouées pendant 24 heures.

**url** `string` *required*

URL HTTPS publique, 2048 caractères au maximum. Les redirections ne sont pas suivies.

**events** `string[]` *required*

Au moins un [type d’événement](https://docs.qwairy.co/fr/developers/integration-webhooks/events.md) : `run.completed`, `run.failed`, `run.cancelled`, `pitch_audit.completed`, `pitch_audit.failed`, `site_audit.completed`, `prompt_suggestions.ready`, `prompt_suggestions.failed` ou `webhook.test`.

**description** `string`

Description libre, 200 caractères au maximum.

**brandIds** `string[]`

Limite l’endpoint à ces workspaces, 100 au maximum. Omettez-le ou envoyez un tableau vide pour recevoir les événements de tous les workspaces de l’équipe.

**enabled** `boolean` (default: true)

Indique si l’endpoint reçoit les événements immédiatement.

## Réponse

Renvoie `201` avec `Location`, `ETag` et l’endpoint, plus le `secret`.

**secret** `string`

Secret de signature. Affiché une seule fois ; il ne peut plus être relu. Renouvelez-le avec [Renouveler le secret de signature](https://docs.qwairy.co/fr/developers/endpoints/webhooks/rotate-secret.md) si vous le perdez.

Les autres champs sont décrits dans [Lister les endpoints de webhook](https://docs.qwairy.co/fr/developers/endpoints/webhooks/list.md).

## Requête et réponse synthétiques

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/webhooks" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: webhook-endpoint-001" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/qwairy","description":"Production receiver","events":["run.completed","run.failed"]}'
```

```json theme={null}
{
  "id": "eeeeeeee-0000-4000-8000-000000000000",
  "url": "https://hooks.example.com/qwairy",
  "description": "Production receiver",
  "events": ["run.completed", "run.failed"],
  "brandIds": [],
  "enabled": true,
  "disabledReason": null,
  "failingSince": null,
  "previousSecretExpiresAt": null,
  "version": 0,
  "createdAt": "2026-10-12T09:00:00.000Z",
  "updatedAt": "2026-10-12T09:00:00.000Z",
  "secret": "synthetic-signing-secret"
}
```

## Erreurs

| Statut | Code | Cause |
| - | - | - |
| `400` | `INVALID_REQUEST` | URL invalide, événement inconnu ou valeur hors plage |
| `409` | `CONFLICT` | La requête entre en conflit avec les endpoints actuels, par exemple la limite de 10 endpoints |
| `409` | `IDEMPOTENCY_CONFLICT` | La clé a été réutilisée avec un corps différent |

Consultez [Codes d’erreur](https://docs.qwairy.co/fr/developers/errors.md) pour les erreurs d’authentification, d’offre, d’idempotence et de serveur. Un jeton sans accès en écriture renvoie `403 API_KEY_READ_ONLY`. Sur `429`, respectez `Retry-After`. Si le limiteur d’écriture est indisponible ou si les écritures sont suspendues, la requête renvoie `503 SERVICE_UNAVAILABLE` et rien ne change.


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