Menyiapkan Webhook untuk acara agen

Webhook mengirimkan POST bertanda tangan ke endpoint kamu sendiri saat sesuatu terjadi, seperti pekerjaan agen yang selesai atau agen yang menunggu persetujuan, sehingga sistem kamu tidak perlu melakukan polling. Artikel ini membahas cara menambahkan endpoint, acara, payload, memverifikasi tanda tangan, dan apa yang terjadi saat pengiriman gagal.

Sebelum kamu mulai#

• Webhook tersedia di paket Pro, Business, dan Custom ("Webhook tersedia di paket Pro ke atas.").
• Hanya pemilik ruang kerja dan admin yang dapat mengelola webhook. Anggota lain akan melihat "Hanya pemilik dan admin yang dapat mengelola webhook".
• Kamu memerlukan alamat https publik yang merespons dengan status 2xx dalam waktu 10 detik.
• Satu ruang kerja dapat memiliki hingga 10 webhook.

Menambahkan webhook#

1. Buka tab Webhook#

   Buka menu ruang kerja, pilih AI agents & API, lalu buka Webhooks. Klik Webhook baru.

   

2. Masukkan endpoint#

   • URL Endpoint: "Alamat HTTPS publik." Contohnya https://example.com/clevera/webhooks.
   • Deskripsi: opsional, maksimal 200 karakter, contohnya "Slack relay".

3. Pilih acara#

   Centang acara yang ingin diterima, atau Semua acara, termasuk yang baru. Acara yang ditandai Segera diterima tetapi "Belum ada yang mengirim acara ini."

   

4. Buat dan simpan rahasia#

   Klik Buat webhook. Rahasia penandatanganan (dimulai dengan whsec_) hanya muncul sekali: "Salin sekarang: kamu tidak akan melihatnya lagi. Gunakan untuk memeriksa header Clevera-Signature." Simpan seperti kata sandi, lalu klik Saya sudah menyimpannya.

5. Kirim acara tes#

   Buka menu ⋯ webhook dan pilih Kirim acara tes. Clevera mengirimkan acara ping bertanda tangan satu kali (tanpa percobaan ulang). "Acara tes terkirim" berarti acara telah meninggalkan Clevera; periksa Pengiriman untuk melihat jawaban endpoint kamu.

Acara#

Acara-acara ini terdaftar sebagai Segera dan belum dikirim: job.progress, video.ready, article.ready, research.completed, insights.weekly.

Acara pekerjaan mencakup pekerjaan yang dimulai agen (melalui token API atau aplikasi yang terhubung), bukan video yang dimulai orang di dalam aplikasi.

Apa yang dikirim Clevera#

Setiap pengiriman adalah POST dengan isi JSON dan header berikut:

Payload membawa ID, tautan, status, dan angka, tidak pernah membawa konten itu sendiri. Untuk membaca video atau artikel yang sudah selesai, panggil API dengan 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" }
  }
}

Verifikasi tanda tangan#

Periksa setiap pengiriman sebelum kamu memercayainya. Tanda tangan adalah HMAC-SHA256, yang dikunci dengan rahasia penandatanganan kamu, dari stempel waktu, titik, dan isi permintaan mentah: <t>.<body>.

1. Baca t dan v1 dari header Clevera-Signature.
2. Hitung HMAC-SHA256(secret, t + "." + rawBody) sebagai hex.
3. Bandingkan dengan v1 dalam waktu konstan.
4. Tolak pengiriman yang t-nya berumur lebih dari 5 menit, agar permintaan yang ditangkap tidak dapat diputar ulang.

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

Gunakan isi persis seperti yang diterima. Mengurai dan menyandikan ulang JSON terlebih dahulu akan mengubah byte dan tanda tangan tidak akan cocok.

Percobaan ulang dan kegagalan#

Pengiriman dianggap berhasil saat endpoint kamu menjawab dengan status 2xx. Status lainnya akan menggagalkan upaya tersebut:

• status lainnya, termasuk pengalihan (3xx tidak diikuti);
• tidak ada jawaban dalam 10 detik (5 detik untuk terhubung);
• alamat yang tidak lagi terhubung ke internet publik.

Clevera mencoba ulang pengiriman yang gagal sebanyak 5 kali, setelah 1 menit, 5 menit, 30 menit, 2 jam, dan 6 jam. Isi respons endpoint kamu tidak pernah dibaca.

Saat 15 pengiriman berturut-turut gagal, webhook akan dimatikan: "Dimatikan setelah 15 pengiriman gagal berturut-turut. Perbaiki endpoint, lalu aktifkan." Pemilik dan admin mendapatkan notifikasi "Webhook ke host dimatikan": "Pengirimannya terus gagal. Perbaiki endpoint, lalu aktifkan kembali." Acara yang terjadi saat webhook mati tidak akan dikirim. Acara tes tidak dihitung dalam hal ini.

Mengelola webhook#

Klik Pengiriman pada webhook untuk melihat log-nya, atau buka menu ⋯ untuk opsi lainnya:

Jika ruang kerja keluar dari paket Pro#

Webhook tetap terdaftar dan masih dapat diedit serta dihapus, tetapi tidak ada yang dikirim. Pengiriman yang menunggu percobaan ulang berakhir sebagai gagal dengan plan_locked, dan Kirim acara tes serta Kirim ulang akan menampilkan "Webhook tidak tersedia di paket kamu." Meningkatkan kembali ke Pro akan memulai pengiriman lagi; tidak ada yang dihapus.

Pemecahan masalah#

Terkait#