# Webhooks

> Référence générée depuis le contrat OpenAPI : Webhooks.

URL : https://docs.fanconvert.ai/fr/api/reference/webhooks

{/* Généré par scripts/generer-reference.mjs depuis openapi/public-v1.json : ne pas modifier à la main. */}

## Enregistrer une adresse qui recevra les événements [#enregistrer-une-adresse-qui-recevra-les-événements]

`POST /public/v1/webhooks` · `createWebhook`

En-tête `Idempotency-Key` obligatoire : voir [Écritures et idempotence](/fr/api/rest/ecritures).

### Paramètres [#paramètres]

| Nom | Où | Type | Requis | Description |
|---|---|---|---|---|
| `Idempotency-Key` | en-tête | string | oui |  |

### Corps de la requête [#corps-de-la-requête]

**`WebhookCreate`**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `url` | string | oui | https://, hôte public, port 443 ou 8443. |
| `events` | "sale.created" \| "emergency.created" \| "ai.paused"[] | oui |  |

### Réponse 201 [#réponse-201]

**`WebhookCreated`**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `webhook` | Webhook | oui |  |
| `secret` | string | oui | Le secret de signature `whsec_…` : affiché UNE fois, gardez-le. |

**`Webhook`**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `id` | string | oui |  |
| `url` | string | oui |  |
| `events` | string[] | oui |  |
| `createdAt` | string (date-time) | oui |  |
| `disabledAt` | string (date-time) \| null | oui |  |
| `disabledReason` | string \| null | oui |  |

### Erreurs possibles [#erreurs-possibles]

`401` · `403` · `404` · `409` · `422` · `429` · `503` — Format des erreurs : [Erreurs](/fr/api/rest/erreurs).

### Exemple [#exemple]

```bash
curl -X POST "https://app.fanconvert.ai/public/v1/webhooks" \
  -H "Authorization: Bearer $FANCONVERT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ … }'
```

## Les webhooks de cette clé [#les-webhooks-de-cette-clé]

`GET /public/v1/webhooks` · `listWebhooks`

### Réponse 200 [#réponse-200]

### Erreurs possibles [#erreurs-possibles-1]

`401` · `403` · `404` · `409` · `422` · `429` · `503` — Format des erreurs : [Erreurs](/fr/api/rest/erreurs).

### Exemple [#exemple-1]

```bash
curl -X GET "https://app.fanconvert.ai/public/v1/webhooks" \
  -H "Authorization: Bearer $FANCONVERT_API_KEY"
```

## Désactiver un webhook (son journal est gardé) [#désactiver-un-webhook-son-journal-est-gardé]

`DELETE /public/v1/webhooks/{endpoint_id}` · `disableWebhook`

### Paramètres [#paramètres-1]

| Nom | Où | Type | Requis | Description |
|---|---|---|---|---|
| `endpoint_id` | chemin | string | oui |  |

### Réponse 200 [#réponse-200-1]

**`Webhook`**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `id` | string | oui |  |
| `url` | string | oui |  |
| `events` | string[] | oui |  |
| `createdAt` | string (date-time) | oui |  |
| `disabledAt` | string (date-time) \| null | oui |  |
| `disabledReason` | string \| null | oui |  |

### Erreurs possibles [#erreurs-possibles-2]

`401` · `403` · `404` · `409` · `422` · `429` · `503` — Format des erreurs : [Erreurs](/fr/api/rest/erreurs).

### Exemple [#exemple-2]

```bash
curl -X DELETE "https://app.fanconvert.ai/public/v1/webhooks/{endpoint_id}" \
  -H "Authorization: Bearer $FANCONVERT_API_KEY"
```

## Le journal des livraisons, les plus récentes d'abord [#le-journal-des-livraisons-les-plus-récentes-dabord]

`GET /public/v1/webhooks/{endpoint_id}/deliveries` · `listWebhookDeliveries`

### Paramètres [#paramètres-2]

| Nom | Où | Type | Requis | Description |
|---|---|---|---|---|
| `endpoint_id` | chemin | string | oui |  |
| `limit` | requête | integer | non |  (défaut : `50`) |
| `cursor` | requête | string \| null | non |  |

### Réponse 200 [#réponse-200-2]

**`DeliveryPage`**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `items` | Delivery[] | oui |  |
| `nextCursor` | string \| null | non |  |

**`Delivery`**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `id` | string | oui |  |
| `eventId` | string | oui |  |
| `eventType` | string | oui |  |
| `status` | "pending" \| "delivered" \| "failed" | oui |  |
| `attempts` | integer | oui |  |
| `lastStatusCode` | integer \| null | oui |  |
| `lastError` | string \| null | oui | Motif court : timeout, connexion, http_<code>, adresse_refusee… |
| `createdAt` | string (date-time) | oui |  |
| `nextAttemptAt` | string (date-time) \| null | oui |  |
| `deliveredAt` | string (date-time) \| null | oui |  |

### Erreurs possibles [#erreurs-possibles-3]

`401` · `403` · `404` · `409` · `422` · `429` · `503` — Format des erreurs : [Erreurs](/fr/api/rest/erreurs).

### Exemple [#exemple-3]

```bash
curl -X GET "https://app.fanconvert.ai/public/v1/webhooks/{endpoint_id}/deliveries" \
  -H "Authorization: Bearer $FANCONVERT_API_KEY"
```

## Envoyer un événement `ping` (aucune donnée) pour tester la réception [#envoyer-un-événement-ping-aucune-donnée-pour-tester-la-réception]

`POST /public/v1/webhooks/{endpoint_id}/ping` · `pingWebhook`

En-tête `Idempotency-Key` obligatoire : voir [Écritures et idempotence](/fr/api/rest/ecritures).

### Paramètres [#paramètres-3]

| Nom | Où | Type | Requis | Description |
|---|---|---|---|---|
| `endpoint_id` | chemin | string | oui |  |

### Réponse 202 [#réponse-202]

**`Webhook`**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `id` | string | oui |  |
| `url` | string | oui |  |
| `events` | string[] | oui |  |
| `createdAt` | string (date-time) | oui |  |
| `disabledAt` | string (date-time) \| null | oui |  |
| `disabledReason` | string \| null | oui |  |

### Erreurs possibles [#erreurs-possibles-4]

`401` · `403` · `404` · `409` · `422` · `429` · `503` — Format des erreurs : [Erreurs](/fr/api/rest/erreurs).

### Exemple [#exemple-4]

```bash
curl -X POST "https://app.fanconvert.ai/public/v1/webhooks/{endpoint_id}/ping" \
  -H "Authorization: Bearer $FANCONVERT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```