ตั้งค่าเว็บฮุคสำหรับเหตุการณ์ของเอเจนต์

เว็บฮุคจะส่ง POST ที่มีการลงลายเซ็นไปยัง endpoint ของคุณทันทีที่มีเหตุการณ์เกิดขึ้น เช่น เมื่อการทำงานของเอเจนต์เสร็จสิ้นหรือเอเจนต์กำลังรอการอนุมัติ เพื่อให้ระบบของคุณไม่ต้องคอยดึงข้อมูล บทความนี้ครอบคลุมถึงการเพิ่ม endpoint, เหตุการณ์ต่างๆ, เพย์โหลด, การตรวจสอบลายเซ็น และสิ่งที่เกิดขึ้นเมื่อการส่งข้อมูลไม่สำเร็จ

ก่อนที่คุณจะเริ่ม#

• เว็บฮุคมีให้ใช้งานในแผน Pro, Business และ Custom ("เว็บฮุคมีให้ใช้งานในแผน Pro ขึ้นไป")
• เฉพาะเจ้าของพื้นที่ทำงานและผู้ดูแลระบบเท่านั้นที่จัดการเว็บฮุคได้ สมาชิกคนอื่นจะเห็นข้อความ "เฉพาะเจ้าของและผู้ดูแลระบบเท่านั้นที่จัดการเว็บฮุคได้"
• คุณต้องมีที่อยู่ https สาธารณะที่ตอบกลับด้วยสถานะ 2xx ภายใน 10 วินาที
• พื้นที่ทำงานหนึ่งแห่งสามารถมีเว็บฮุคได้สูงสุด 10 รายการ

เพิ่มเว็บฮุค#

1. เปิดแท็บเว็บฮุค#

   เปิดเมนูพื้นที่ทำงาน เลือก AI agents & API จากนั้นเปิด Webhooks แล้วคลิก เว็บฮุคใหม่

   

2. ป้อน endpoint#

   • Endpoint URL: "ที่อยู่ HTTPS สาธารณะ" เช่น https://example.com/clevera/webhooks
   • คำอธิบาย: ไม่บังคับ สูงสุด 200 ตัวอักษร เช่น "Slack relay"

3. เลือกเหตุการณ์#

   เลือกเหตุการณ์ที่ต้องการรับ หรือเลือก เหตุการณ์ทั้งหมด รวมถึงเหตุการณ์ใหม่ เหตุการณ์ที่ทำเครื่องหมายว่า เร็วๆ นี้ จะถูกยอมรับแต่ "ยังไม่มีเหตุการณ์นี้ส่งออกมาในขณะนี้"

   

4. สร้างและบันทึกรหัสลับ#

   คลิก สร้างเว็บฮุค รหัสลับการลงลายเซ็น (ขึ้นต้นด้วย whsec_) จะแสดงเพียงครั้งเดียว: "คัดลอกตอนนี้: คุณจะไม่เห็นมันอีก ใช้เพื่อตรวจสอบส่วนหัว Clevera-Signature" บันทึกไว้เหมือนรหัสผ่าน จากนั้นคลิก ฉันบันทึกไว้แล้ว

5. ส่งเหตุการณ์ทดสอบ#

   เปิดเมนู ⋯ ของเว็บฮุคแล้วเลือก ส่งเหตุการณ์ทดสอบ Clevera จะส่งเหตุการณ์ ping ที่มีการลงลายเซ็นหนึ่งครั้ง (ไม่มีการลองใหม่) "ส่งเหตุการณ์ทดสอบแล้ว" หมายความว่าเหตุการณ์ออกจาก Clevera แล้ว ให้ตรวจสอบ การส่งข้อมูล เพื่อดูคำตอบจาก endpoint ของคุณ

เหตุการณ์#

เหตุการณ์เหล่านี้แสดงเป็น เร็วๆ นี้ และยังไม่มีการส่งออกมา: job.progress, video.ready, article.ready, research.completed, insights.weekly

เหตุการณ์ของงานจะครอบคลุมงานที่เอเจนต์เริ่ม (ผ่านโทเค็น API หรือแอปที่เชื่อมต่อ) ไม่ใช่วิดีโอที่ผู้คนเริ่มในแอป

สิ่งที่ Clevera ส่ง#

การส่งข้อมูลทุกครั้งคือ POST ที่มีเนื้อหา JSON และส่วนหัวดังนี้:

เพย์โหลดจะประกอบด้วยรหัส, ลิงก์, สถานะ และตัวเลข โดยไม่มีเนื้อหาจริง หากต้องการอ่านวิดีโอหรือบทความที่เสร็จสิ้น ให้เรียกใช้ API ด้วยโทเค็น

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

ตรวจสอบลายเซ็น#

ตรวจสอบการส่งข้อมูลทุกครั้งก่อนที่คุณจะเชื่อถือ ลายเซ็นคือ HMAC-SHA256 ที่ใช้รหัสลับการลงลายเซ็นของคุณ, การประทับเวลา, จุด และเนื้อหาคำขอ ดิบ: <t>.<body>

1. อ่าน t และ v1 จากส่วนหัว Clevera-Signature
2. คำนวณ HMAC-SHA256(secret, t + "." + rawBody) เป็นเลขฐานสิบหก
3. เปรียบเทียบกับ v1 ในเวลาคงที่
4. ปฏิเสธการส่งข้อมูลที่มี t เก่าเกิน 5 นาที เพื่อไม่ให้คำขอที่ถูกดักจับถูกนำมาเล่นซ้ำได้

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

ใช้เนื้อหาตามที่ได้รับมาทุกประการ การแยกวิเคราะห์และเข้ารหัส JSON ใหม่ก่อนจะทำให้ไบต์เปลี่ยนไปและลายเซ็นจะไม่ตรงกัน

การลองใหม่และความล้มเหลว#

การส่งข้อมูลจะถือว่าสำเร็จเมื่อ endpoint ของคุณตอบกลับด้วยสถานะ 2xx หากเป็นอย่างอื่นจะถือว่าความพยายามล้มเหลว:

• สถานะอื่นๆ รวมถึงการเปลี่ยนเส้นทาง (3xx จะไม่ถูกติดตาม)
• ไม่มีการตอบกลับภายใน 10 วินาที (5 วินาทีในการเชื่อมต่อ)
• ที่อยู่ที่ไม่มีการแก้ไขไปยังอินเทอร์เน็ตสาธารณะอีกต่อไป

Clevera จะลองส่งข้อมูลที่ล้มเหลวใหม่ 5 ครั้ง หลังจากผ่านไป 1 นาที, 5 นาที, 30 นาที, 2 ชั่วโมง และ 6 ชั่วโมง เนื้อหาการตอบกลับของ endpoint ของคุณจะไม่ถูกอ่าน

เมื่อการส่งข้อมูลล้มเหลวติดต่อกัน 15 ครั้ง เว็บฮุคจะถูกปิด: "ปิดใช้งานหลังจากส่งข้อมูลล้มเหลวติดต่อกัน 15 ครั้ง แก้ไข endpoint แล้วเปิดใช้งาน" เจ้าของและผู้ดูแลระบบจะได้รับการแจ้งเตือน "เว็บฮุคไปยัง host ถูกปิด": "การส่งข้อมูลล้มเหลวอย่างต่อเนื่อง แก้ไข endpoint แล้วเปิดใช้งานอีกครั้ง" เหตุการณ์ที่เกิดขึ้นในขณะที่ปิดอยู่จะไม่ถูกส่ง เหตุการณ์ทดสอบจะไม่ถูกนับรวมในนี้

จัดการเว็บฮุค#

คลิก การส่งข้อมูล บนเว็บฮุคเพื่อดูบันทึก หรือเปิดเมนู ⋯ เพื่อดูตัวเลือกอื่นๆ:

หากพื้นที่ทำงานออกจากแผน Pro#

เว็บฮุคจะยังคงอยู่ในรายการและสามารถแก้ไขหรือลบได้ แต่จะไม่มีการส่งข้อมูลใดๆ การส่งข้อมูลที่รอการลองใหม่จะสิ้นสุดลงด้วยสถานะไม่สำเร็จ plan_locked และ ส่งเหตุการณ์ทดสอบ กับ ส่งซ้ำ จะแสดงข้อความ "เว็บฮุคไม่ได้อยู่ในแผนของคุณ" การอัปเกรดกลับเป็น Pro จะเริ่มส่งข้อมูลอีกครั้ง โดยไม่มีข้อมูลใดถูกลบ

การแก้ไขปัญหา#

ที่เกี่ยวข้อง#