# Webhooks

> Reference generated from the OpenAPI contract: Webhooks.

URL : https://docs.fanconvert.ai/en/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`

`Idempotency-Key` header required: see [Writes and idempotency](/en/api/rest/ecritures).

### Parameters [#parameters]

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | yes |  |

### Request body [#request-body]

**`WebhookCreate`**

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

### Response 201 [#response-201]

**`WebhookCreated`**

| Field | Type | Required | Description |
|---|---|---|---|
| `webhook` | Webhook | yes |  |
| `secret` | string | yes | Le secret de signature `whsec_…` : affiché UNE fois, gardez-le. |

**`Webhook`**

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `url` | string | yes |  |
| `events` | string[] | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `disabledAt` | string (date-time) \| null | yes |  |
| `disabledReason` | string \| null | yes |  |

### Possible errors [#possible-errors]

`401` · `403` · `404` · `409` · `422` · `429` · `503` — Error format: [Errors](/en/api/rest/erreurs).

### Example [#example]

```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`

### Response 200 [#response-200]

### Possible errors [#possible-errors-1]

`401` · `403` · `404` · `409` · `422` · `429` · `503` — Error format: [Errors](/en/api/rest/erreurs).

### Example [#example-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`

### Parameters [#parameters-1]

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `endpoint_id` | path | string | yes |  |

### Response 200 [#response-200-1]

**`Webhook`**

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `url` | string | yes |  |
| `events` | string[] | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `disabledAt` | string (date-time) \| null | yes |  |
| `disabledReason` | string \| null | yes |  |

### Possible errors [#possible-errors-2]

`401` · `403` · `404` · `409` · `422` · `429` · `503` — Error format: [Errors](/en/api/rest/erreurs).

### Example [#example-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`

### Parameters [#parameters-2]

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `endpoint_id` | path | string | yes |  |
| `limit` | query | integer | no |  (default : `50`) |
| `cursor` | query | string \| null | no |  |

### Response 200 [#response-200-2]

**`DeliveryPage`**

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | Delivery[] | yes |  |
| `nextCursor` | string \| null | no |  |

**`Delivery`**

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

### Possible errors [#possible-errors-3]

`401` · `403` · `404` · `409` · `422` · `429` · `503` — Error format: [Errors](/en/api/rest/erreurs).

### Example [#example-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`

`Idempotency-Key` header required: see [Writes and idempotency](/en/api/rest/ecritures).

### Parameters [#parameters-3]

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `endpoint_id` | path | string | yes |  |

### Response 202 [#response-202]

**`Webhook`**

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `url` | string | yes |  |
| `events` | string[] | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `disabledAt` | string (date-time) \| null | yes |  |
| `disabledReason` | string \| null | yes |  |

### Possible errors [#possible-errors-4]

`401` · `403` · `404` · `409` · `422` · `429` · `503` — Error format: [Errors](/en/api/rest/erreurs).

### Example [#example-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)"
```