Konfigurowanie webhooków dla zdarzeń agenta

Webhook wysyła podpisane POST do Twojego punktu końcowego w momencie, gdy coś się wydarzy, na przykład gdy praca agenta dobiegnie końca lub agent będzie oczekiwał na zatwierdzenie, dzięki czemu Twoje systemy nie muszą wysyłać zapytań (poll). Ten artykuł omawia dodawanie punktu końcowego, zdarzenia, ładunek, weryfikację podpisu oraz to, co dzieje się, gdy dostarczenia kończą się niepowodzeniem.

Zanim zaczniesz#

• Webhooki są dostępne w planach Pro, Business i Custom („Webhooki są dostępne w planie Pro i wyższych”).
• Tylko właściciel obszaru roboczego i administratorzy zarządzają webhookami. Pozostali członkowie widzą komunikat „Tylko właściciele i administratorzy zarządzają webhookami”.
• Potrzebujesz publicznego adresu https, który odpowiada statusem 2xx w ciągu 10 sekund.
• Obszar roboczy może mieć maksymalnie 10 webhooków.

Dodaj webhook#

1. Otwórz kartę Webhooki#

   Otwórz menu obszaru roboczego, wybierz AI agents & API, a następnie otwórz Webhooks. Kliknij Nowy webhook.

   

2. Wprowadź punkt końcowy#

   • Endpoint URL: „Publiczny adres HTTPS”. Na przykład https://example.com/clevera/webhooks.
   • Opis: opcjonalny, do 200 znaków, na przykład „Slack relay”.

3. Wybierz zdarzenia#

   Zaznacz zdarzenia, które chcesz otrzymywać, lub wybierz Wszystkie zdarzenia, w tym nowe. Zdarzenia oznaczone jako Wkrótce są akceptowane, ale „Żadne zdarzenie nie wysyła jeszcze tego powiadomienia”.

   

4. Utwórz go i zapisz klucz#

   Kliknij Utwórz webhook. Klucz podpisu (zaczyna się od whsec_) wyświetla się tylko raz: „Skopiuj go teraz: nie zobaczysz go ponownie. Użyj go do sprawdzenia nagłówka Clevera-Signature”. Zapisz go jak hasło, a następnie kliknij Zapisano.

5. Wyślij zdarzenie testowe#

   Otwórz menu ⋯ webhooka i wybierz Wyślij zdarzenie testowe. Clevera wysyła podpisane zdarzenie ping jednorazowo (bez ponownych prób). „Zdarzenie testowe wysłane” oznacza, że opuściło ono Clevera; sprawdź Dostarczenia, aby zobaczyć odpowiedź swojego punktu końcowego.

Zdarzenia#

Te zdarzenia są wymienione jako Wkrótce i nie są jeszcze wysyłane: job.progress, video.ready, article.ready, research.completed, insights.weekly.

Zdarzenia dotyczące pracy obejmują zadania uruchamiane przez agentów (za pośrednictwem tokena API lub połączonej aplikacji), a nie filmy uruchamiane przez użytkowników w aplikacji.

Co wysyła Clevera#

Każde dostarczenie to POST z treścią JSON i następującymi nagłówkami:

Ładunki zawierają identyfikatory, linki, statusy i liczby, nigdy same treści. Aby odczytać gotowy film lub artykuł, wywołaj API za pomocą tokena.

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

Weryfikacja podpisu#

Sprawdź każde dostarczenie, zanim mu zaufasz. Podpis to HMAC-SHA256, kluczowany Twoim kluczem podpisu, znacznikiem czasu, kropką i surową treścią żądania: <t>.<body>.

1. Odczytaj t i v1 z nagłówka Clevera-Signature.
2. Oblicz HMAC-SHA256(secret, t + "." + rawBody) w formacie szesnastkowym.
3. Porównaj go z v1 w czasie stałym.
4. Odrzuć dostarczenia, których t jest starsze niż 5 minut, aby przechwycone żądanie nie mogło zostać odtworzone.

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

Użyj treści dokładnie w takiej formie, w jakiej została odebrana. Parsowanie i ponowne kodowanie JSON zmienia bajty, przez co podpis nie będzie pasował.

Ponowne próby i błędy#

Dostarczenie uznaje się za udane, gdy punkt końcowy odpowie statusem 2xx. Każda inna odpowiedź powoduje niepowodzenie próby:

• jakikolwiek inny status, w tym przekierowania (3xx nie są śledzone);
• brak odpowiedzi w ciągu 10 sekund (5 sekund na połączenie);
• adres, który nie rozwiązuje się już do publicznego internetu.

Clevera ponawia nieudane dostarczenie 5 razy, po 1 minucie, 5 minutach, 30 minutach, 2 godzinach i 6 godzinach. Treść odpowiedzi Twojego punktu końcowego nigdy nie jest odczytywana.

Gdy 15 dostarczeń z rzędu zakończy się niepowodzeniem, webhook zostaje wyłączony: „Wyłączono po 15 nieudanych dostarczeniach z rzędu. Napraw punkt końcowy, a następnie włącz go”. Właściciel i administratorzy otrzymują powiadomienie „Webhook dla host wyłączony”: „Dostarczenia ciągle kończyły się niepowodzeniem. Napraw punkt końcowy, a następnie włącz go ponownie”. Zdarzenia, które wystąpią w czasie, gdy jest on wyłączony, nie są wysyłane. Zdarzenia testowe nie wliczają się do tego limitu.

Zarządzanie webhookiem#

Kliknij Dostarczenia przy webhooku, aby zobaczyć jego dziennik, lub otwórz menu ⋯, aby uzyskać dostęp do pozostałych opcji:

Jeśli obszar roboczy opuści plan Pro#

Webhooki pozostają na liście i nadal można je edytować oraz usuwać, ale nic nie jest wysyłane. Dostarczenia oczekujące na ponowną próbę kończą się niepowodzeniem z plan_locked, a Wyślij zdarzenie testowe oraz Ponów dostarczenie wyświetlają komunikat „Webhooki nie są dostępne w Twoim planie”. Powrót do planu Pro wznawia wysyłanie; nic nie jest usuwane.

Rozwiązywanie problemów#

Powiązane#