## Vue d'ensemble

Les webhooks vous permettent de recevoir des événements KennHosting sur votre serveur dès qu'un changement d'état se produit (activation VPS, domaine enregistré, wallet crédité...).

**Scope requis :** `reseller:webhooks`

## Configurer l'URL webhook

```http
PUT /api/v1/reseller/webhook
```

```bash
curl -X PUT "https://kennhosting.com/api/v1/reseller/webhook" \
  -H "Authorization: Bearer kh_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://votre-site.cm/kh-webhook",
    "secret": "votre_secret_hmac"
  }'
```

**Réponse :**

```json
{
  "success": true,
  "data": {
    "url": "https://votre-site.cm/kh-webhook",
    "has_secret": true
  }
}
```

## Consulter la configuration

```http
GET /api/v1/reseller/webhook
```

```json
{
  "success": true,
  "data": {
    "url": "https://votre-site.cm/kh-webhook",
    "has_secret": true
  }
}
```

<Note>
  Le secret n'est jamais retourné en clair dans les réponses — seul `has_secret: true/false` est indiqué.
</Note>

## Tester la connexion

```http
POST /api/v1/reseller/webhook/test
```

Envoie un événement fictif signé à votre URL configurée.

```json
{
  "success": true,
  "data": {
    "url": "https://votre-site.cm/kh-webhook",
    "status_code": 200,
    "delivered": true,
    "error": null
  }
}
```

## Signature des événements

Chaque webhook est signé avec HMAC-SHA256 :

```
X-KennHosting-Signature: sha256=HMAC(body, secret)
```

**Vérification en PHP :**

```php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_KENNHOSTING_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $payload, 'votre_secret_hmac');

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Signature invalide');
}

$event = json_decode($payload, true);
// Traiter $event['event']
```

## Événements disponibles

| Événement | Description |
|-----------|-------------|
| `hosting.created` | Compte d'hébergement créé |
| `domain.registered` | Domaine enregistré |
| `vps.provisioning` | VPS en cours de création |
| `vps.activated` | VPS opérationnel |
| `email.provisioning` | Email Pro en cours de création |
| `email.activated` | Email Pro actif |
| `wallet.debited` | Débit wallet |
| `wallet.credited` | Crédit wallet |

## Format d'un événement

```json
{
  "event": "vps.activated",
  "sandbox": false,
  "timestamp": "2026-06-12T19:00:00Z",
  "data": {
    "client_id": 1,
    "order_uuid": "b1912d95-...",
    "server_id": 12345,
    "ipv4": "1.2.3.4",
    "status": "running"
  }
}
```

Les événements sandbox incluent toujours `"sandbox": true`.