Webhooks instellen voor agent-gebeurtenissen

Een webhook stuurt een ondertekende POST naar je eigen eindpunt op het moment dat er iets gebeurt, zoals wanneer de taak van een agent is voltooid of een agent wacht op goedkeuring, zodat je systemen niet hoeven te pollen. Dit artikel behandelt het toevoegen van een eindpunt, de gebeurtenissen, de payload, het verifiëren van de handtekening en wat er gebeurt als leveringen mislukken.

Voordat je begint#

• Webhooks zijn beschikbaar in de Pro-, Business- en Custom-abonnementen ("Webhooks zijn beschikbaar vanaf Pro.").
• Alleen de eigenaar van de werkruimte en beheerders beheren webhooks. Andere leden zien "Alleen eigenaren en beheerders beheren webhooks".
• Je hebt een openbaar https-adres nodig dat binnen 10 seconden antwoordt met een 2xx-status.
• Een werkruimte kan maximaal 10 webhooks hebben.

Een webhook toevoegen#

1. Open het tabblad Webhooks#

   Open het menu van de werkruimte, kies AI agents & API en open vervolgens Webhooks. Klik op Nieuwe webhook.

   

2. Voer het eindpunt in#

   • Endpoint URL: "Een openbaar HTTPS-adres." Bijvoorbeeld https://example.com/clevera/webhooks.
   • Beschrijving: optioneel, maximaal 200 tekens, bijvoorbeeld "Slack relay".

3. Kies de gebeurtenissen#

   Vink de gebeurtenissen aan die je wilt ontvangen, of Alle gebeurtenissen, inclusief nieuwe. Gebeurtenissen gemarkeerd als Binnenkort worden geaccepteerd, maar "Nog niets verzendt deze gebeurtenis."

   

4. Maak het aan en sla het geheim op#

   Klik op Webhook aanmaken. Het Ondertekeningsgeheim (het begint met whsec_) wordt één keer getoond: "Kopieer het nu: je zult het niet opnieuw zien. Gebruik het om de Clevera-Signature-header te controleren." Sla het op als een wachtwoord en klik vervolgens op Ik heb het opgeslagen.

5. Testgebeurtenis verzenden#

   Open het ⋯-menu van de webhook en kies Testgebeurtenis verzenden. Clevera stuurt één keer een ondertekende ping-gebeurtenis (geen nieuwe pogingen). "Testgebeurtenis verzonden" betekent dat het Clevera heeft verlaten; controleer Leveringen voor het antwoord van je eindpunt.

Gebeurtenissen#

Deze gebeurtenissen staan vermeld als Binnenkort en worden nog niet verzonden: job.progress, video.ready, article.ready, research.completed, insights.weekly.

Taakgebeurtenissen hebben betrekking op taken die agents starten (via een API-token of een gekoppelde app), niet op video's die mensen in de app starten.

Wat Clevera verzendt#

Elke levering is een POST met een JSON-body en deze headers:

Payloads bevatten ID's, links, statussen en getallen, nooit de inhoud zelf. Om een voltooide video of artikel te lezen, roep je de API aan met een token.

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

De handtekening verifiëren#

Controleer elke levering voordat je deze vertrouwt. De handtekening is een HMAC-SHA256, versleuteld met je ondertekeningsgeheim, van de tijdstempel, een punt en de onbewerkte request-body: <t>.<body>.

1. Lees t en v1 uit de Clevera-Signature-header.
2. Bereken HMAC-SHA256(secret, t + "." + rawBody) als hex.
3. Vergelijk het met v1 in constante tijd.
4. Wijs leveringen af waarvan de t meer dan 5 minuten oud is, zodat een onderschept verzoek niet opnieuw kan worden afgespeeld.

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

Gebruik de body precies zoals ontvangen. Het eerst parseren en opnieuw coderen van de JSON verandert de bytes en de handtekening zal niet overeenkomen.

Nieuwe pogingen en mislukkingen#

Een levering telt als afgeleverd wanneer je eindpunt antwoordt met een 2xx-status. Al het andere zorgt voor een mislukte poging:

• elke andere status, inclusief redirects (3xx worden niet gevolgd);
• geen antwoord binnen 10 seconden (5 seconden om verbinding te maken);
• een adres dat niet langer naar het openbare internet verwijst.

Clevera probeert een mislukte levering 5 keer opnieuw, na 1 minuut, 5 minuten, 30 minuten, 2 uur en 6 uur. De response-body van je eindpunt wordt nooit gelezen.

Wanneer 15 leveringen achter elkaar mislukken, wordt de webhook uitgeschakeld: "Uitgeschakeld na 15 mislukte leveringen achter elkaar. Herstel het eindpunt en schakel het vervolgens in." De eigenaar en beheerders krijgen een "Webhook naar host uitgeschakeld"-melding: "De leveringen bleven mislukken. Herstel het eindpunt en schakel het vervolgens weer in." Gebeurtenissen die plaatsvinden terwijl deze is uitgeschakeld, worden niet verzonden. Testgebeurtenissen tellen hier niet voor mee.

Een webhook beheren#

Klik op Leveringen bij een webhook om het logboek te bekijken, of open het ⋯-menu voor de rest:

Als de werkruimte Pro verlaat#

Webhooks blijven in de lijst staan en kunnen nog steeds worden bewerkt en verwijderd, maar er wordt niets verzonden. Leveringen die wachten op een nieuwe poging eindigen als mislukt met plan_locked, en Testgebeurtenis verzenden en Opnieuw leveren geven aan "Webhooks zijn niet in je abonnement inbegrepen." Upgraden naar Pro zorgt ervoor dat er weer wordt verzonden; er wordt niets verwijderd.

Probleemoplossing#

Gerelateerd#