Temsilci etkinlikleri için Webhook'ları ayarlama

Bir webhook, bir temsilcinin işinin bitmesi veya bir temsilcinin onay beklemesi gibi bir durum gerçekleştiği anda kendi uç noktanıza imzalı bir POST gönderir, böylece sistemlerinizin sürekli sorgulama yapmasına gerek kalmaz. Bu makale; bir uç nokta eklemeyi, etkinlikleri, yükü, imza doğrulamayı ve teslimatlar başarısız olduğunda neler yaşandığını kapsar.

Başlamadan önce#

• Webhook'lar Pro, Business ve Custom planlarında mevcuttur ("Webhook'lar Pro ve üzeri planlarda mevcuttur.").
• Webhook'ları yalnızca çalışma alanı sahibi ve yöneticileri yönetebilir. Diğer üyeler "Webhook'ları yalnızca sahipler ve yöneticiler yönetebilir" uyarısını görür.
• 10 saniye içinde 2xx durumuyla yanıt veren herkese açık bir https adresine ihtiyacınız vardır.
• Bir çalışma alanında en fazla 10 webhook bulunabilir.

Webhook ekleme#

1. Webhook'lar sekmesini açma#

   Çalışma alanı menüsünü açın, AI agents & API seçeneğini belirleyin ve ardından Webhooks kısmına girin. Yeni webhook düğmesine tıklayın.

   

2. Uç noktayı girme#

   • Endpoint URL: "Herkese açık bir HTTPS adresi." Örneğin https://example.com/clevera/webhooks.
   • Açıklama: isteğe bağlı, en fazla 200 karakter, örneğin "Slack aktarıcısı".

3. Etkinlikleri seçme#

   Almak istediğiniz etkinlikleri işaretleyin veya Yeni etkinlikler dahil tüm etkinlikler seçeneğini belirleyin. Yakında olarak işaretlenen etkinlikler kabul edilir ancak "Henüz bu etkinliği gönderen bir şey yok."

   

4. Oluşturma ve gizli anahtarı kaydetme#

   Create webhook düğmesine tıklayın. Signing secret (whsec_ ile başlar) yalnızca bir kez gösterilir: "Şimdi kopyalayın: tekrar göremezsiniz. Clevera-Signature başlığını kontrol etmek için kullanın." Bir parola gibi saklayın ve ardından Kaydettim düğmesine tıklayın.

5. Test etkinliği gönderme#

   Webhook'un ⋯ menüsünü açın ve Test etkinliği gönder seçeneğini belirleyin. Clevera bir kez imzalı ping etkinliği gönderir (yeniden deneme yapılmaz). "Test etkinliği gönderildi" ifadesi, etkinliğin Clevera'dan çıktığı anlamına gelir; uç noktanızın yanıtı için Teslimatlar kısmını kontrol edin.

Etkinlikler#

Bu etkinlikler Yakında olarak listelenmiştir ve henüz gönderilmemektedir: job.progress, video.ready, article.ready, research.completed, insights.weekly.

İş etkinlikleri, insanların uygulamada başlattığı videoları değil, temsilcilerin (bir API anahtarı veya bağlı bir uygulama aracılığıyla) başlattığı işleri kapsar.

Clevera'nın gönderdikleri#

Her teslimat, JSON gövdesine ve şu başlıklara sahip bir POST'dır:

Yükler; kimlikleri, bağlantıları, durumları ve sayıları taşır, içeriğin kendisini asla taşımaz. Tamamlanmış bir videoyu veya makaleyi okumak için bir belirteçle API'yi çağırın.

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

İmzayı doğrulama#

Güvenmeden önce her teslimatı kontrol edin. İmza, imzalama gizli anahtarınızla anahtarlanmış bir HMAC-SHA256'dır; zaman damgası, bir nokta ve ham istek gövdesinden oluşur: <t>.<body>.

1. Clevera-Signature başlığından t ve v1 değerlerini okuyun.
2. HMAC-SHA256(secret, t + "." + rawBody) değerini onaltılık (hex) olarak hesaplayın.
3. Bunu sabit sürede v1 ile karşılaştırın.
4. Yakalanan bir isteğin tekrar oynatılmaması için t değeri 5 dakikadan eski olan teslimatları reddedin.

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

Gövdeyi tam olarak alındığı gibi kullanın. JSON'ı önce ayrıştırıp yeniden kodlamak baytları değiştirir ve imza eşleşmez.

Yeniden denemeler ve hatalar#

Bir teslimat, uç noktanız 2xx durumuyla yanıt verdiğinde teslim edilmiş sayılır. Başka herhangi bir durum denemeyi başarısız kılar:

• yönlendirmeler dahil diğer tüm durumlar (3xx takip edilmez);
• 10 saniye içinde yanıt gelmemesi (bağlanmak için 5 saniye);
• artık genel internete çözümlenmeyen bir adres.

Clevera başarısız bir teslimatı 1 dakika, 5 dakika, 30 dakika, 2 saat ve 6 saat sonra olmak üzere 5 kez yeniden dener. Uç noktanızın yanıt gövdesi asla okunmaz.

Arka arkaya 15 teslimat başarısız olduğunda, webhook kapatılır: "Arka arkaya 15 başarısız teslimattan sonra kapatıldı. Uç noktayı düzeltin ve ardından açın." Sahip ve yöneticiler "host için webhook kapatıldı" şeklinde bir bildirim alır: "Teslimatları başarısız olmaya devam etti. Uç noktayı düzeltin ve ardından tekrar açın." Kapalıyken gerçekleşen etkinlikler gönderilmez. Test etkinlikleri bu sayıya dahil edilmez.

Webhook yönetimi#

Günlüğünü görmek için bir webhook üzerindeki Teslimatlar seçeneğine tıklayın veya geri kalanı için ⋯ menüsünü açın:

Çalışma alanı Pro planından ayrılırsa#

Webhook'lar listelenmeye devam eder ve düzenlenip silinebilir, ancak hiçbir şey gönderilmez. Yeniden deneme bekleyen teslimatlar plan_locked ile başarısız olarak sonuçlanır ve Test etkinliği gönder ile Yeniden teslim et seçenekleri "Webhook'lar planınızda mevcut değil" uyarısını verir. Tekrar Pro'ya yükseltmek gönderimi başlatır; hiçbir şey silinmez.

Sorun giderme#

İlgili#