Webhooks für Agenten-Events einrichten

Ein Webhook sendet einen signierten POST an deinen eigenen Endpunkt, sobald etwas passiert – zum Beispiel, wenn der Job eines Agenten abgeschlossen ist oder auf eine Genehmigung wartet –, damit deine Systeme nicht pollen müssen. Dieser Artikel behandelt das Hinzufügen eines Endpunkts, die Events, das Payload, die Überprüfung der Signatur und was passiert, wenn Zustellungen fehlschlagen.

Bevor du beginnst#

• Webhooks sind in den Pro-, Business- und Custom-Plänen verfügbar („Webhooks sind ab Pro verfügbar“).
• Nur der Workspace-Inhaber und Administratoren können Webhooks verwalten. Andere Mitglieder sehen „Nur Inhaber und Administratoren können Webhooks verwalten“.
• Du benötigst eine öffentliche https-Adresse, die innerhalb von 10 Sekunden mit einem 2xx-Status antwortet.
• Ein Workspace kann bis zu 10 Webhooks haben.

Einen Webhook hinzufügen#

1. Den Tab „Webhooks“ öffnen#

   Öffne das Workspace-Menü, wähle AI agents & API und öffne dann Webhooks. Klicke auf Neuer Webhook.

   

2. Den Endpunkt eingeben#

   • Endpoint URL: „Eine öffentliche HTTPS-Adresse.“ Zum Beispiel https://example.com/clevera/webhooks.
   • Beschreibung: optional, bis zu 200 Zeichen, zum Beispiel „Slack-Relay“.

3. Die Events auswählen#

   Wähle die Events aus, die du empfangen möchtest, oder Alle Events, einschließlich neuer. Events, die mit Bald markiert sind, werden akzeptiert, aber „Bisher sendet nichts dieses Event.“

   

4. Erstellen und das Geheimnis speichern#

   Klicke auf Webhook erstellen. Das Signing secret (es beginnt mit whsec_) wird einmalig angezeigt: „Kopiere es jetzt: Du wirst es nicht noch einmal sehen. Verwende es, um den Clevera-Signature-Header zu prüfen.“ Speichere es wie ein Passwort und klicke dann auf Ich habe es gespeichert.

5. Ein Test-Event senden#

   Öffne das ⋯-Menü des Webhooks und wähle Test-Event senden. Clevera sendet einmalig ein signiertes ping-Event (keine Wiederholungsversuche). „Test-Event gesendet“ bedeutet, dass es Clevera verlassen hat; prüfe Zustellungen auf die Antwort deines Endpunkts.

Events#

Diese Events sind als Bald gelistet und werden noch nicht gesendet: job.progress, video.ready, article.ready, research.completed, insights.weekly.

Job-Events decken Jobs ab, die Agenten starten (über einen API-Token oder eine verbundene App), nicht Videos, die Personen in der App starten.

Was Clevera sendet#

Jede Zustellung ist ein POST mit einem JSON-Body und diesen Headern:

Payloads enthalten IDs, Links, Status und Zahlen, niemals den Inhalt selbst. Um ein fertiges Video oder einen Artikel zu lesen, rufe die API mit einem Token auf.

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

Die Signatur überprüfen#

Prüfe jede Zustellung, bevor du ihr vertraust. Die Signatur ist ein HMAC-SHA256, verschlüsselt mit deinem Signing Secret, basierend auf dem Zeitstempel, einem Punkt und dem rohen Request-Body: <t>.<body>.

1. Lese t und v1 aus dem Clevera-Signature-Header.
2. Berechne HMAC-SHA256(secret, t + "." + rawBody) als Hex-Wert.
3. Vergleiche ihn mit v1 in konstanter Zeit.
4. Weise Zustellungen zurück, deren t älter als 5 Minuten ist, damit ein abgefangener Request nicht wiederholt werden kann.

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

Verwende den Body exakt so, wie er empfangen wurde. Das Parsen und erneute Kodieren des JSON ändert die Bytes, wodurch die Signatur nicht mehr übereinstimmt.

Wiederholungsversuche und Fehler#

Eine Zustellung gilt als zugestellt, wenn dein Endpunkt mit einem 2xx-Status antwortet. Alles andere führt zum Fehlschlag des Versuchs:

• jeder andere Status, einschließlich Weiterleitungen (3xx werden nicht gefolgt);
• keine Antwort innerhalb von 10 Sekunden (5 Sekunden für den Verbindungsaufbau);
• eine Adresse, die nicht mehr im öffentlichen Internet aufgelöst werden kann.

Clevera wiederholt eine fehlgeschlagene Zustellung 5 Mal, nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden. Der Response-Body deines Endpunkts wird nie gelesen.

Wenn 15 Zustellungen in Folge fehlschlagen, wird der Webhook ausgeschaltet: „Nach 15 fehlgeschlagenen Zustellungen in Folge ausgeschaltet. Repariere den Endpunkt und schalte ihn dann ein.“ Der Inhaber und die Administratoren erhalten eine Benachrichtigung „Webhook für host ausgeschaltet“: „Die Zustellungen sind ständig fehlgeschlagen. Repariere den Endpunkt und schalte ihn dann wieder ein.“ Events, die während der Deaktivierung auftreten, werden nicht gesendet. Test-Events zählen nicht dazu.

Einen Webhook verwalten#

Klicke bei einem Webhook auf Zustellungen, um das Protokoll zu sehen, oder öffne das ⋯-Menü für die restlichen Optionen:

Wenn der Workspace den Pro-Plan verlässt#

Webhooks bleiben gelistet und können weiterhin bearbeitet und gelöscht werden, aber es wird nichts gesendet. Zustellungen, die auf einen Wiederholungsversuch warten, enden mit plan_locked als fehlgeschlagen, und Test-Event senden sowie Erneut zustellen zeigen „Webhooks sind nicht in deinem Plan enthalten.“ Ein Upgrade zurück auf Pro startet den Versand erneut; es wird nichts gelöscht.

Fehlerbehebung#

Verwandte Themen#