Konfigurera webhooks för agenthändelser

En webhook skickar en signerad POST till din egen slutpunkt i samma ögonblick som något händer, till exempel att en agents jobb slutförs eller att en agent väntar på godkännande, så att dina system inte behöver polla. Den här artikeln täcker hur du lägger till en slutpunkt, händelserna, nyttolasten, verifiering av signaturen och vad som händer när leveranser misslyckas.

Innan du börjar#

• Webhooks ingår i planerna Pro, Business och Custom ("Webhooks ingår i Pro och uppåt.").
• Endast arbetsytans ägare och administratörer kan hantera webhooks. Andra medlemmar ser "Endast ägare och administratörer kan hantera webhooks".
• Du behöver en offentlig https-adress som svarar med en 2xx-status inom 10 sekunder.
• En arbetsyta kan ha upp till 10 webhooks.

Lägg till en webhook#

1. Öppna fliken Webhooks#

   Öppna menyn för arbetsytan, välj AI agents & API och öppna sedan Webhooks. Klicka på Ny webhook.

   

2. Ange slutpunkten#

   • Slutpunkts-URL: "En offentlig HTTPS-adress." Till exempel https://example.com/clevera/webhooks.
   • Beskrivning: valfritt, upp till 200 tecken, till exempel "Slack-relä".

3. Välj händelserna#

   Markera händelserna du vill ta emot, eller Alla händelser, inklusive nya. Händelser markerade som Snart accepteras men "Ingenting skickar denna händelse än."

   

4. Skapa den och spara hemligheten#

   Klicka på Skapa webhook. Signeringshemligheten (den börjar med whsec_) visas en gång: "Kopiera den nu: du kommer inte att se den igen. Använd den för att kontrollera Clevera-Signature-huvudet." Spara den som ett lösenord och klicka sedan på Jag har sparat den.

5. Skicka en test-händelse#

   Öppna webhookens ⋯-meny och välj Skicka test-händelse. Clevera skickar en signerad ping-händelse en gång (inga återförsök). "Test-händelse skickad" betyder att den lämnade Clevera; kontrollera Leveranser för din slutpunkts svar.

Händelser#

Dessa händelser är listade som Snart och skickas inte än: job.progress, video.ready, article.ready, research.completed, insights.weekly.

Jobbhändelser täcker jobb som agenter startar (via en API-nyckel eller en ansluten app), inte videor som personer startar i appen.

Vad Clevera skickar#

Varje leverans är en POST med en JSON-kropp och dessa huvuden:

Nyttolaster bär på id:n, länkar, statusar och nummer, aldrig själva innehållet. För att läsa en färdig video eller artikel, anropa API:et med en nyckel.

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

Verifiera signaturen#

Kontrollera varje leverans innan du litar på den. Signaturen är en HMAC-SHA256, nycklad med din signeringshemlighet, av tidsstämpeln, en punkt och den råa förfrågningskroppen: <t>.<body>.

1. Läs t och v1 från Clevera-Signature-huvudet.
2. Beräkna HMAC-SHA256(secret, t + "." + rawBody) som hex.
3. Jämför den med v1 i konstant tid.
4. Avvisa leveranser vars t är mer än 5 minuter gammal, så att en fångad förfrågan inte kan spelas upp igen.

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

Använd kroppen exakt som den togs emot. Att tolka och koda om JSON först ändrar byten och signaturen kommer inte att matcha.

Återförsök och fel#

En leverans räknas som levererad när din slutpunkt svarar med en 2xx-status. Allt annat gör att försöket misslyckas:

• alla andra statusar, inklusive omdirigeringar (3xx följs inte);
• inget svar inom 10 sekunder (5 sekunder för att ansluta);
• en adress som inte längre kan matchas mot det offentliga internet.

Clevera gör 5 återförsök för en misslyckad leverans, efter 1 minut, 5 minuter, 30 minuter, 2 timmar och 6 timmar. Din slutpunkts svarskropp läses aldrig.

När 15 leveranser i rad misslyckas vid varje försök, stängs webhooken av: "Avstängd efter 15 misslyckade leveranser i rad. Fixa slutpunkten och aktivera den sedan." Ägaren och administratörerna får ett meddelande om att "Webhook till host stängdes av": "Dess leveranser fortsatte att misslyckas. Fixa slutpunkten och slå på den igen." Händelser som inträffar medan den är avstängd skickas inte. Testhändelser räknas inte in i detta.

Hantera en webhook#

Klicka på Leveranser på en webhook för att se dess logg, eller öppna dess ⋯-meny för resten:

Om arbetsytan lämnar Pro#

Webhooks förblir listade och kan fortfarande redigeras och tas bort, men ingenting skickas. Leveranser som väntar på ett återförsök slutar som misslyckade med plan_locked, och Skicka test-händelse samt Skicka igen säger "Webhooks ingår inte i din plan." Att uppgradera tillbaka till Pro startar sändningen igen; ingenting tas bort.

Felsökning#

Relaterat#