Webhooks

Les webhooks poussent des events vers vos systèmes au moment où ils se produisent : une alerte s’ouvre, un sampling hebdomadaire se termine, un correctif est vérifié, une commande est attribuée à un assistant IA… Plutôt que d’interroger l’API en boucle, vous exposez un endpoint HTTPS et Skoup l’appelle.

Usages typiques : ouvrir un ticket quand une alerte critique s’ouvre, envoyer les résultats du sampling hebdomadaire dans un entrepôt de données, déclencher un workflow n8n ou Zapier, rafraîchir le dashboard d’un client.

Mettre en place un endpoint

Exposez une URL HTTPS

Votre endpoint doit accepter des requêtes POST avec un corps JSON, en HTTPS, sur un hôte joignable publiquement. Les adresses qui résolvent vers une IP privée, loopback ou link-local sont refusées. Pour tester depuis votre machine, passez par un tunnel (ngrok, Cloudflare Tunnel…) — voir Bonnes pratiques.

Déclarez-le

Dans Réglages → Développeurs → Webhooks, cliquez sur Ajouter un endpoint, collez l’URL, choisissez les types d’events à recevoir (ou tous) et, si besoin, limitez-le à certaines marques.

Ou par l’API, avec une clé qui porte le scope webhooks:write :


curl https://api.skoup.ai/v1/webhook_endpoints \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/skoup",
    "enabled_events": ["alert.created", "alert.resolved", "sampling.completed"],
    "description": "Alertes vers notre ticketing"
  }'

La réponse contient le secret de signature de l’endpoint (whsec_…). L’API ne le renvoie que dans cette réponse ; il reste consultable dans le dashboard derrière un bouton Révéler.

Vérifiez la signature

Chaque livraison est signée avec le secret de l’endpoint. Vérifiez-la toujours avant de faire confiance à un payload — voir Vérifier les signatures.

Répondez vite en 2xx

Renvoyez n’importe quel statut 2xx en moins de 10 secondes. Tout le reste — ou un délai dépassé — compte comme un échec et fait l’objet de nouvelles tentatives.

L’objet event

Chaque livraison est un POST dont le corps est un event :


{
  "id": "evt_8KpL3mQn6RsT9uVw2xYz4A",
  "object": "event",
  "type": "alert.created",
  "api_version": "v1",
  "created": "2026-09-21T02:47:12Z",
  "livemode": true,
  "brand": "br_2xKq8Fh3LmN9pQrT4vWy6Z",
  "data": {
    "object": {
      "id": "alrt_5TgH2kLm8NpQ3rSv6wXy9A",
      "object": "alert",
      "kind": "price_hallucination",
      "severity": "critical",
      "status": "new",
      "…": "…"
    }
  }
}

Champ	Description
`id`	ID unique de l’event. Un même event livré deux fois garde le même ID.
`type`	Ce qui s’est passé, sous la forme `ressource.action`. Voir Types d’events.
`api_version`	Version du format de payload. Toujours `v1` aujourd’hui.
`created`	Moment où l’event s’est produit (UTC).
`livemode`	`false` pour les events produits en mode test.
`brand`	La marque concernée.
`data.object`	L’objet concerné, exactement sous la forme renvoyée par l’endpoint `GET` correspondant.
`data.previous_attributes`	Sur les events `*.updated`, les valeurs précédentes des champs qui ont changé.

En-têtes HTTP

En-tête	Valeur
`Content-Type`	`application/json`
`User-Agent`	`Skoup-Webhooks/1.0`
`X-Skoup-Signature`	`t=…,v1=…` — voir Vérifier les signatures
`X-Skoup-Event-Id`	L’ID de l’event (`evt_…`), pour dédupliquer.
`X-Skoup-Event-Type`	Le type de l’event, pour router sans lire le corps.
`X-Skoup-Delivery-Id`	L’ID de cette tentative de livraison (`whd_…`).

Rattraper avec l’API Events

Les events restent aussi disponibles par l’API pendant 30 jours : de quoi rattraper une panne ou réconcilier régulièrement.


curl "https://api.skoup.ai/v1/events?type=alert.created&limit=100" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Un webhook vous dit **qu’**il s’est passé quelque chose ; l’event porte une photo de l’objet à ce moment-là. Pour son état le plus récent, relisez l’objet à partir de son ID.