## Principe des webhooks

Au lieu de interroger l'API régulièrement (polling), les webhooks permettent à KennHosting de **pousser des notifications** vers votre application dès qu'un événement se produit.

```
Événement KennHosting → POST vers votre URL → Votre app traite l'événement
```

## Configurer un webhook

**Espace client → Mon compte → API → Webhooks → Ajouter**

Ou via l'API :

```http
POST /v1/webhooks
Content-Type: application/json
```

```json
{
  "url": "https://votre-app.com/webhooks/kennhosting",
  "events": [
    "service.activated",
    "payment.completed",
    "domain.registered"
  ]
}
```

| Champ | Description |
|-------|-------------|
| `url` | URL HTTPS publique de votre endpoint (HTTP non accepté) |
| `events` | Liste des événements autorisés (pas de wildcard `*`) |

La clé `secret` est générée côté serveur et renvoyée dans la réponse de création.

## Structure d'un payload (exemple)

```json
{
  "event": "service.activated",
  "created_at": "2026-04-13T10:30:00+00:00",
  "data": {
    "message": "payload dépendant de l'événement"
  }
}
```

## Vérification de signature

Chaque webhook est signé avec votre secret. **Vérifiez toujours la signature** avant de traiter le payload pour éviter les requêtes malveillantes.

L'en-tête `X-KennHosting-Signature` contient la signature HMAC-SHA256 du body :

```
X-KennHosting-Signature: sha256=abc123def456...
```

### Vérification en PHP (Laravel)

```php
use Illuminate\Http\Request;

public function handle(Request $request): JsonResponse
{
    $signature = $request->header('X-KennHosting-Signature');
    $secret    = config('services.kennhosting.webhook_secret');
    
    $expected = 'sha256=' . hash_hmac('sha256', $request->getContent(), $secret);

    if (!hash_equals($expected, $signature)) {
        return response()->json(['error' => 'Signature invalide'], 401);
    }

    $event = $request->json('event');
    $data  = $request->json('data');

    match ($event) {
        'service.activated' => $this->handleServiceActivated($data),
        'payment.completed' => $this->handlePaymentCompleted($data),
        'domain.registered' => $this->handleDomainRegistered($data),
        default             => null,
    };

    return response()->json(['received' => true]);
}
```

### Vérification en Node.js

```javascript
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

app.post('/webhooks/kennhosting', (req, res) => {
  const sig = req.headers['x-kennhosting-signature'];
  if (!verifySignature(req.rawBody, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Signature invalide' });
  }

  const { event, data } = req.body;
  // Traiter l'événement...
  res.json({ received: true });
});
```

<Warning>
  Votre endpoint doit répondre avec un **code HTTP 2xx** dans les **5 secondes**. Au-delà, KennHosting considère la livraison comme échouée et retente jusqu'à 3 fois avec un délai exponentiel (1 min, 10 min, 1 heure).
</Warning>

## Événements autorisés

| Événement |
|-----------|
| `service.activated` |
| `service.suspended` |
| `service.cancelled` |
| `payment.completed` |
| `payment.failed` |
| `domain.registered` |
| `domain.renewed` |
| `ticket.created` |
| `ticket.replied` |

## Tester vos webhooks

Depuis votre espace client, vous pouvez envoyer un événement de test :

**Mon compte → API → Webhooks → [votre webhook] → Envoyer un test**

Ou via l'API :

```http
POST /v1/webhooks/{id}/test
Content-Type: application/json
```

```json
{
  "event": "test"
}
```

## Historique des livraisons

```http
GET /v1/webhooks/{id}/deliveries
```

```json
{
  "data": [
    {
      "delivery_id": "del_01HXYZ001",
      "event": "service.activated",
      "status": "success",
      "http_status": 200,
      "duration_ms": 245,
      "attempted_at": "2024-06-15T10:30:00Z"
    },
    {
      "delivery_id": "del_01HXYZ002",
      "event": "payment.completed",
      "status": "failed",
      "http_status": 500,
      "error": "Connection timeout",
      "retries": 3,
      "attempted_at": "2024-06-15T11:00:00Z"
    }
  ]
}
```