​
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 : 
POST /v1/webhooks
Content-Type: application/json

{
  "url": "https://votre-app.com/webhooks/kennhosting",
  "events": [
    "service.activated",
    "payment.completed",
    "domain.registered"
  ]
}
ChampDescription
urlURL HTTPS publique de votre endpoint (HTTP non accepté)
eventsListe 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)

{
  "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)

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

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 });
});
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).

​
É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 : 
POST /v1/webhooks/{id}/test
Content-Type: application/json

{
  "event": "test"
}

​
Historique des livraisons

GET /v1/webhooks/{id}/deliveries

{
  "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"
    }
  ]
}