Thiết lập Webhook cho các sự kiện của tác nhân

Webhook gửi một POST đã ký đến endpoint của riêng bạn ngay khi có sự kiện xảy ra, chẳng hạn như khi công việc của tác nhân hoàn tất hoặc tác nhân đang chờ phê duyệt, vì vậy hệ thống của bạn không cần phải thực hiện polling. Bài viết này đề cập đến việc thêm endpoint, các sự kiện, payload, xác minh chữ ký và những gì xảy ra khi lượt gửi thất bại.

Trước khi bạn bắt đầu#

• Webhook có sẵn trên các gói Pro, Business và Custom ("Webhook có sẵn trên gói Pro trở lên.").
• Chỉ chủ sở hữu và quản trị viên không gian làm việc mới quản lý được Webhook. Các thành viên khác sẽ thấy "Chỉ chủ sở hữu và quản trị viên mới quản lý được Webhook".
• Bạn cần một địa chỉ https công khai phản hồi với trạng thái 2xx trong vòng 10 giây.
• Một không gian làm việc có thể có tối đa 10 Webhook.

Thêm Webhook#

1. Mở tab Webhook#

   Mở menu không gian làm việc, chọn AI agents & API, sau đó mở Webhooks. Nhấp vào Webhook mới.

   

2. Nhập endpoint#

   • URL endpoint: "Một địa chỉ HTTPS công khai." Ví dụ: https://example.com/clevera/webhooks.
   • Mô tả: tùy chọn, tối đa 200 ký tự, ví dụ: "Slack relay".

3. Chọn các sự kiện#

   Đánh dấu các sự kiện muốn nhận, hoặc chọn Tất cả sự kiện, bao gồm cả sự kiện mới. Các sự kiện được đánh dấu Sắp có sẽ được chấp nhận nhưng "Chưa có gì gửi sự kiện này."

   

4. Tạo và lưu mã bí mật#

   Nhấp vào Tạo Webhook. Mã bí mật ký (bắt đầu bằng whsec_) chỉ hiển thị một lần: "Sao chép ngay: bạn sẽ không thấy lại nó nữa. Sử dụng nó để kiểm tra header Clevera-Signature." Lưu nó như mật khẩu, sau đó nhấp vào Tôi đã lưu nó.

5. Gửi sự kiện kiểm thử#

   Mở menu ⋯ của Webhook và chọn Gửi sự kiện kiểm thử. Clevera gửi một sự kiện ping đã ký một lần (không thử lại). "Đã gửi sự kiện kiểm thử" nghĩa là nó đã rời khỏi Clevera; hãy kiểm tra Lượt gửi để xem phản hồi từ endpoint của bạn.

Sự kiện#

Các sự kiện này được liệt kê là Sắp có và chưa được gửi: job.progress, video.ready, article.ready, research.completed, insights.weekly.

Các sự kiện công việc bao gồm các công việc mà tác nhân bắt đầu (thông qua token API hoặc ứng dụng được kết nối), không phải video mà mọi người bắt đầu trong ứng dụng.

Những gì Clevera gửi#

Mỗi lượt gửi là một POST với phần thân JSON và các header sau:

Payload mang theo ID, liên kết, trạng thái và số, không bao giờ mang theo nội dung thực tế. Để đọc video hoặc bài viết đã hoàn thành, hãy gọi API bằng 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" }
  }
}

Xác minh chữ ký#

Kiểm tra mọi lượt gửi trước khi bạn tin tưởng nó. Chữ ký là HMAC-SHA256, được tạo bằng mã bí mật ký của bạn, dấu thời gian, một dấu chấm và phần thân yêu cầu thô: <t>.<body>.

1. Đọc t và v1 từ header Clevera-Signature.
2. Tính HMAC-SHA256(secret, t + "." + rawBody) dưới dạng hex.
3. So sánh nó với v1 trong thời gian không đổi.
4. Từ chối các lượt gửi có t cũ hơn 5 phút, để yêu cầu bị bắt không thể bị phát lại.

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

Sử dụng phần thân chính xác như đã nhận. Việc phân tích cú pháp và mã hóa lại JSON trước sẽ làm thay đổi các byte và chữ ký sẽ không khớp.

Thử lại và thất bại#

Một lượt gửi được coi là đã gửi khi endpoint của bạn phản hồi với trạng thái 2xx. Bất kỳ trạng thái nào khác đều khiến nỗ lực đó thất bại:

• bất kỳ trạng thái nào khác, bao gồm cả chuyển hướng (3xx không được theo sau);
• không có phản hồi trong vòng 10 giây (5 giây để kết nối);
• một địa chỉ không còn phân giải được trên internet công cộng.

Clevera thử lại lượt gửi thất bại 5 lần, sau 1 phút, 5 phút, 30 phút, 2 giờ và 6 giờ. Phần thân phản hồi của endpoint của bạn không bao giờ được đọc.

Khi 15 lượt gửi liên tiếp thất bại trong mọi nỗ lực, Webhook sẽ bị tắt: "Đã tắt sau 15 lượt gửi thất bại liên tiếp. Hãy sửa endpoint, sau đó bật lại." Chủ sở hữu và quản trị viên nhận được thông báo "Webhook tới host đã bị tắt": "Các lượt gửi của nó liên tục thất bại. Hãy sửa endpoint, sau đó bật lại." Các sự kiện xảy ra khi nó bị tắt sẽ không được gửi. Các sự kiện kiểm thử không được tính vào đây.

Quản lý Webhook#

Nhấp vào Lượt gửi trên một Webhook để xem nhật ký của nó, hoặc mở menu ⋯ để xem các tùy chọn còn lại:

Nếu không gian làm việc rời khỏi gói Pro#

Webhook vẫn được liệt kê và vẫn có thể chỉnh sửa và xóa, nhưng không có gì được gửi đi. Các lượt gửi chờ thử lại sẽ kết thúc với trạng thái thất bại plan_locked, và Gửi sự kiện kiểm thử cùng Gửi lại sẽ hiển thị "Webhook không có trên gói của bạn." Nâng cấp lại lên Pro sẽ bắt đầu gửi lại; không có gì bị xóa.

Khắc phục sự cố#

Liên quan#