Events & endpoints webhook

Un event est la trace de quelque chose qui s’est passé : une alerte ouverte, une tâche déplacée, un sampling terminé, une commande venue de ChatGPT. Skoup garde chaque event 30 jours et l’envoie aux endpoints webhook qui écoutent son type — des URL HTTPS à vous, chacune avec son propre secret de signature. data.object a exactement la forme renvoyée par le GET correspondant : un event et une lecture ne se contredisent jamais. La liste complète des types est générée depuis la plateforme elle-même.

Les endpoints se créent dans Réglages → Développeurs → Webhooks, ou par l’API — pratique pour n8n, Zapier ou un script qui s’abonne lui-même. Ils vivent dans le mode de la clé qui les a créés : une clé de test gère des endpoints de test, qui reçoivent les events des appels en mode test (livemode: false).

Cycle de vie d’une livraison

pendingsucceededretryingfailed

Une livraison attend un 2xx sous 10 s. En cas d'échec, elle est retentée 5 fois (1 min, 5 min, 30 min, 2 h, 12 h). Un endpoint sans aucun succès pendant 3 jours est désactivé et ses owners reçoivent un e-mail.

Je veux…

Je veux…	Appel
Abonner une URL à certains events	`POST /v1/webhook_endpoints` (`url`, `enabled_events`)
M’abonner à tout	Même appel avec `enabled_events: ["*"]`
Mettre un endpoint en pause	`PATCH /v1/webhook_endpoints/{endpoint}` avec `disabled: true`
Supprimer un endpoint	`DELETE /v1/webhook_endpoints/{endpoint}`
Rattraper un retard après une panne	`GET /v1/events?type=alert.created`
Relire un event	`GET /v1/events/{event}`
Rejouer une livraison, envoyer un event de test	Réglages → Développeurs → Webhooks (dashboard)

Scopes : webhooks:write pour les endpoints, events:read pour les events.

Scénario : un workflow n8n qui s’abonne lui-même


curl -X POST https://api.skoup.ai/v1/webhook_endpoints \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://n8n.example.com/webhook/skoup","enabled_events":["alert.created","task.created"],"description":"n8n · triage"}'

Cette réponse est la seule qui porte secret (whsec_…) : stockez-le pour vérifier l’en-tête X-Skoup-Signature de chaque livraison.

Pièges

Vérifiez la signature sur le corps brut, et dédupliquez sur l’id de l’event : une livraison peut arriver deux fois.
HTTPS et adresses publiques uniquement. Les adresses privées, loopback et metadata cloud sont refusées ; utilisez un tunnel pour tester en local.
Répondez vite, travaillez après. Accusez réception en 2xx puis traitez en arrière-plan : au-delà de 10 s la livraison compte comme échouée.
Les types inconnus sont refusés : enabled_events doit lister des types du catalogue, ou *.