Configurer des webhooks pour les événements d'agent

Un webhook envoie une requête POST signée à votre propre point de terminaison dès qu'un événement se produit, comme la fin d'un travail d'agent ou un agent en attente d'approbation, afin que vos systèmes n'aient pas à effectuer de sondage. Cet article explique comment ajouter un point de terminaison, les événements, la charge utile, la vérification de la signature et ce qui se passe en cas d'échec des livraisons.

Avant de commencer#

• Les webhooks sont disponibles sur les forfaits Pro, Business et Custom (« Les webhooks sont disponibles à partir du forfait Pro »).
• Seuls le propriétaire de l'espace de travail et les administrateurs peuvent gérer les webhooks. Les autres membres voient le message « Seuls les propriétaires et les administrateurs peuvent gérer les webhooks ».
• Vous avez besoin d'une adresse https publique qui répond avec un statut 2xx en moins de 10 secondes.
• Un espace de travail peut avoir jusqu'à 10 webhooks.

Ajouter un webhook#

1. Ouvrir l'onglet Webhooks#

   Ouvrez le menu de l'espace de travail, choisissez AI agents & API, puis ouvrez Webhooks. Cliquez sur Nouveau webhook.

   

2. Saisir le point de terminaison#

   • URL du point de terminaison : « Une adresse HTTPS publique. » Par exemple https://example.com/clevera/webhooks.
   • Description : facultative, jusqu'à 200 caractères, par exemple « Relais Slack ».

3. Choisir les événements#

   Cochez les événements à recevoir, ou Tous les événements, y compris les nouveaux. Les événements marqués Bientôt sont acceptés mais « Aucun événement de ce type n'est encore envoyé. »

   

4. Créer le webhook et enregistrer le secret#

   Cliquez sur Créer un webhook. Le Secret de signature (il commence par whsec_) ne s'affiche qu'une seule fois : « Copiez-le maintenant : vous ne le verrez plus. Utilisez-le pour vérifier l'en-tête Clevera-Signature. » Enregistrez-le comme un mot de passe, puis cliquez sur Je l'ai enregistré.

5. Envoyer un événement de test#

   Ouvrez le menu ⋯ du webhook et choisissez Envoyer un événement de test. Clevera envoie un événement ping signé une seule fois (sans nouvelle tentative). « Événement de test envoyé » signifie qu'il a quitté Clevera ; vérifiez les Livraisons pour voir la réponse de votre point de terminaison.

Événements#

Ces événements sont marqués comme Bientôt et ne sont pas encore envoyés : job.progress, video.ready, article.ready, research.completed, insights.weekly.

Les événements de travail concernent les tâches lancées par les agents (via un jeton API ou une application connectée), et non les vidéos lancées par les utilisateurs dans l'application.

Ce que Clevera envoie#

Chaque livraison est une requête POST avec un corps JSON et les en-têtes suivants :

Les charges utiles contiennent des identifiants, des liens, des statuts et des nombres, jamais le contenu lui-même. Pour lire une vidéo ou un article terminé, appelez l'API avec un jeton.

{
  "id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
  "event": "job.succeeded",
  "created_at": "2026-10-20T14:03:11Z",
  "data": {
    "job": {
      "id": "job_8k2m4n6p8r0t2v4x",
      "kind": "video.create",
      "status": "succeeded",
      "error_code": null,
      "subject": { "type": "video", "id": "vid_example" },
      "credits_spent": 64
    },
    "needs_input": null,
    "workspace": { "id": "tm_example" }
  }
}

{
  "id": "0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
  "event": "approval.requested",
  "created_at": "2026-10-20T14:01:02Z",
  "data": {
    "approval": {
      "id": "apr_example",
      "kind": "spend",
      "status": "pending",
      "credits_high": 80,
      "expires_at": "2026-10-21T14:01:02Z",
      "decided_at": null,
      "url": "https://app.clevera.ai/agents?tab=requests&team=tm_example"
    },
    "job": { "id": "job_8k2m4n6p8r0t2v4x", "kind": "video.create" },
    "workspace": { "id": "tm_example" }
  }
}

Vérifier la signature#

Vérifiez chaque livraison avant de lui faire confiance. La signature est un HMAC-SHA256, généré avec votre secret de signature, à partir de l'horodatage, d'un point et du corps de la requête brut : <t>.<body>.

1. Lisez t et v1 depuis l'en-tête Clevera-Signature.
2. Calculez HMAC-SHA256(secret, t + "." + rawBody) en hexadécimal.
3. Comparez-le avec v1 en temps constant.
4. Rejetez les livraisons dont le t a plus de 5 minutes, afin qu'une requête capturée ne puisse pas être rejouée.

import crypto from 'node:crypto';

export function verifyClevera(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
  const t = Number(parts.t);
  if (!parts.v1 || !Number.isInteger(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

import hashlib, hmac, time

def verify_clevera(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(","))
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or not v1 or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

function verifyClevera(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
    parse_str(str_replace(',', '&', $header), $parts);
    $t = $parts['t'] ?? '';
    $v1 = $parts['v1'] ?? '';
    if (! ctype_digit($t) || $v1 === '' || abs(time() - (int) $t) > $tolerance) {
        return false;
    }
    return hash_equals(hash_hmac('sha256', $t.'.'.$rawBody, $secret), $v1);
}

Utilisez le corps exactement tel qu'il a été reçu. Analyser et réencoder le JSON modifie les octets et la signature ne correspondra plus.

Tentatives et échecs#

Une livraison est considérée comme effectuée lorsque votre point de terminaison répond avec un statut 2xx. Tout autre résultat entraîne l'échec de la tentative :

• tout autre statut, y compris les redirections (les 3xx ne sont pas suivies) ;
• aucune réponse dans les 10 secondes (5 secondes pour se connecter) ;
• une adresse qui ne se résout plus sur l'internet public.

Clevera effectue 5 tentatives pour une livraison échouée, après 1 minute, 5 minutes, 30 minutes, 2 heures et 6 heures. Le corps de la réponse de votre point de terminaison n'est jamais lu.

Lorsque 15 livraisons consécutives échouent, le webhook est désactivé : « Désactivé après 15 échecs de livraison consécutifs. Corrigez le point de terminaison, puis activez-le. » Le propriétaire et les administrateurs reçoivent une notification « Webhook vers hôte désactivé » : « Ses livraisons ont continué d'échouer. Corrigez le point de terminaison, puis réactivez-le. » Les événements qui se produisent pendant qu'il est désactivé ne sont pas envoyés. Les événements de test ne sont pas comptabilisés dans ce total.

Gérer un webhook#

Cliquez sur Livraisons sur un webhook pour voir son journal, ou ouvrez son menu ⋯ pour le reste :

Si l'espace de travail quitte le forfait Pro#

Les webhooks restent listés et peuvent toujours être modifiés et supprimés, mais rien n'est envoyé. Les livraisons en attente d'une nouvelle tentative échouent avec plan_locked, et Envoyer un événement de test ainsi que Relivrer indiquent « Les webhooks ne sont pas inclus dans votre forfait. » La mise à niveau vers le forfait Pro relance les envois ; rien n'est supprimé.

Dépannage#

Connexe#