เว็บฮุค

webhook จะบอกเซิร์ฟเวอร์ของคุณเมื่อมีเหตุการณ์บางอย่างเกิดขึ้น เช่น วิดีโอจบมันช่วยให้คุณไม่ต้องตรวจสอบ GET /v1/job/{id} Webhook ถูกจัดการด้วยคีย์API เดียวกับAPIอื่น ๆ ภายใต้ https://reigniter.ai/api/webhooks

กิจกรรม

กิจกรรม	ส่งเมื่อ
video.completed	การเรนเดอร์เสร็จสมบูรณ์ payload มี download_urlลิงก์ที่ใช้งานได้ 7 วัน
video.failed	การเรนเดอร์ล้มเหลวการเรนเดอร์ที่คุณยกเลิกจะไม่ส่งข้อมูลนี้
training.invited	ผู้เรียนจะได้รับมอบหมายโมดูลและส่งหน้าการฝึกอบรมของตน
training.completed	ผู้เรียนที่มีชื่อจะจบโมดูลหนึ่ง payload จะมีคะแนน (ที่เซิร์ฟเวอร์ทําเครื่องหมาย), passed และหน้าผลลัพธ์ของพวกเขา
training.passed / training.failed	ส่งพร้อม training.completed, เทียบกับคะแนนผ่านของโมดูลหมดเวลาถือว่าไม่ผ่าน
training.overdue	ผู้เรียนยังไม่เสร็จภายในกําหนดส่งหนึ่งครั้งต่อคําเชิญ
training.certificate_expiring	ใบรับรองจะหมดอายุภายใน 30 วันหนึ่งครั้งต่อใบรับรองหนึ่งครั้ง
post.published	โพสต์หนึ่งถูกเผยแพร่บน YouTube, TikTok, LinkedIn, Facebook หรือ Instagrampayload มีแพลตฟอร์ม บัญชี และ url รวมถึงลิงก์ไปยังโพสต์เมื่อแพลตฟอร์มให้ลิงก์
post.failed	ไม่สามารถเผยแพร่โพสต์ได้ reason คําตอบของแพลตฟอร์มนี้ด้วยถ้อยคําง่าย ๆ
credits.low	ยอดคงเหลือลดลงเหลือ 10 เครดิตหรือน้อยกว่าหนึ่งครั้งต่อหนึ่งหยด
credits.purchased	เครดิตถูกเพิ่มเข้าบัญชี
subscription.created	การสมัครแผนเริ่มต้นขึ้น
subscription.canceled	มีการยกเลิกการสมัครแผน
user.signup	บัญชีถูกสร้างขึ้นแล้ว
user.onboarded	บัญชีเสร็จสมบูรณ์การเริ่มต้นใช้งาน

GET /api/webhooks/events ส่งคืนรายการนี้

ตั้งค่าเว็บฮุค

1. สร้างจุดเชื่อมต่อ บนเซิร์ฟเวอร์ของคุณที่รับคําขอ POST พร้อม JSON body และตอบกลับ 2xx อย่างรวดเร็วต้องสามารถเข้าถึงได้บนอินเทอร์เน็ตสาธารณะที่อยู่เครือข่ายส่วนตัวและท้องถิ่นจะถูกปฏิเสธ

2. สมัครรับ ข้อมูลเพื่อเข้าร่วมกิจกรรม webhook หนึ่งตัวฟังเหตุการณ์หนึ่งรายการ;สร้างหนึ่งตัวต่อเหตุการณ์ที่คุณต้องการ

   curl

   curl https://reigniter.ai/api/webhooks/hooks \
     -H "Authorization: Bearer $REIGNITER_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "event": "video.completed",
       "webhook_url": "https://hooks.example.com/reignitor",
       "description": "Post finished videos to our CMS"
     }'

   JavaScript

   const res = await fetch('https://reigniter.ai/api/webhooks/hooks', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.REIGNITER_API_KEY}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       event: 'video.completed',
       webhook_url: 'https://hooks.example.com/reignitor',
       description: 'Post finished videos to our CMS',
     }),
   });
   const { hook, secret } = await res.json();

   Python

   res = requests.post(
       "https://reigniter.ai/api/webhooks/hooks",
       headers={"Authorization": f"Bearer {os.environ['REIGNITER_API_KEY']}"},
       json={
           "event": "video.completed",
           "webhook_url": "https://hooks.example.com/reignitor",
           "description": "Post finished videos to our CMS",
       },
   )
   data = res.json()
   hook, secret = data["hook"], data["secret"]

3. เก็บ secret จากการตอบกลับ 201 คุณต้องใช้มันเพื่อตรวจสอบลายเซ็น

   คำเตือน

   ความลับการลงนามจะแสดงเพียงครั้งเดียวการอ่านในภายหลังจะคืน has_secret: true แทนถ้าคุณทําหาย ให้ลบเว็บฮุกและสร้างใหม่อีกครั้ง

4. ส่งการทดสอบPOST /api/webhooks/hooks/{id}/test ส่งเหตุการณ์ ping ที่ลงนามไปยัง URL ของคุณและแจ้งคําตอบว่า endpoint ของคุณตอบว่าอย่างไร:

   { "delivered": true, "status": 200 }

การสมัครรับเหตุการณ์และ URL เดียวกันอีกครั้งจะไม่สร้างไฟล์ซ้ํามันจะคืน webhook เดิมพร้อม reused: true และเปิดใหม่อีกครั้ง

ลักษณะของการจัดส่ง

ทุกครั้งที่ส่งของคือ POST ที่มีตัว JSON:

{
  "event": "video.completed",
  "payload": {
    "job_id": "7d2e4b10-5c3a-4f8e-a1b2-9c0d8e7f6a54",
    "user_id": "3f1c2a9e-8b7d-4c1e-9f0a-2d6b5e4c3a21",
    "output_url": "https://cdn.example.com/exports/7d2e4b10.mp4",
    "canvas_id": null,
    "scene_count": 4,
    "scenes_failed": 0,
    "credits_charged": 12
  },
  "emitted_at": "2026-09-25T10:15:00.000Z",
  "delivery_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
}

video.failedมีjob_id, user_id, canvas_id และ reason

จับคู่payload.job_idกับ job_idที่คุณได้จาก POST /v1/render

และหัวข้อเหล่านี้:

ส่วนหัว	มูลค่า
X-Reigniter-Event	ชื่อเหตุการณ์
X-Reigniter-Delivery	รหัสประจําตัวเฉพาะสําหรับการจัดส่งนี้รหัสนี้จะเหมือนเดิมเมื่อมีการทดลองส่งอีกครั้ง
X-Reigniter-Timestamp	เวลายูนิกซ์ (วินาที) เมื่อมีการเซ็นชื่อการส่งมอบ
X-Reigniter-Signature	sha256= และหกเหลี่ยม HMAC-SHA256 ของ {timestamp}.{raw body}ที่บันทึกความลับของคุณ

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

ตรวจสอบทุกการจัดส่งก่อนที่คุณจะเชื่อถือ:

1. อ่านเนื้อหาคําขอ ดิบ ก่อน JSON แยกวิเคราะห์ใด ๆ
2. สร้างสตริง {X-Reigniter-Timestamp}.{raw body}
3. คํานวณ HMAC-SHA256 ด้วยรหัสลับของคุณเป็นเลขฐานหกเหลี่ยม แล้วเพิ่ม sha256= ไว้ข้างหน้า
4. เปรียบเทียบกับ X-Reigniter-Signature โดยใช้การเปรียบเทียบแบบเวลาคงที่
5. ปฏิเสธการจัดส่งหากเวลาประทับเกิน 5 นาที

JavaScript

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyReigniterWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-reigniter-timestamp'];
  const received = headers['x-reigniter-signature'] ?? '';
  if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  return a.length === b.length && timingSafeEqual(a, b);
}

Python

import hashlib, hmac, time

def verify_reignitor_webhook(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers.get("X-Reigniter-Timestamp")
    received = headers.get("X-Reigniter-Signature", "")
    if not timestamp or abs(time.time() - int(timestamp)) > 300:
        return False

    signed = f"{timestamp}.".encode() + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

การส่งมอบและการทดลองใหม่

• แต่ละการจัดส่งจะรอสูงสุด 10 วินาทีเพื่อให้ปลายทางของคุณตอบกลับ
• 5xx, 429, timeout หรือข้อผิดพลาดเครือข่ายจะถูกลองใหม่ โดยพยายามรวมสูงสุด 3 ครั้ง ห่างกันประมาณหนึ่งวินาที
• 4xxอื่นจะไม่ถูกลองใหม่
• การลองใหม่จะยังคง X-Reigniter-Delivery เดิมใช้มันเพื่อละเลยการส่งของที่คุณจัดการไปแล้ว
• หลังจากส่งไม่สําเร็จติดต่อกัน 20 ครั้ง webhook จะถูกปิด GET /api/webhooks/hooks แสดงข้อผิดพลาด active: false และข้อผิดพลาดล่าสุดใน last_status แก้ไขอุปกรณ์ปลายทางของคุณ แล้วเปิดใหม่ด้วย PATCH /api/webhooks/hooks/{id} และ { "active": true }

ตอบ 2xx ทันทีที่คุณเก็บของเสร็จ แล้วค่อยทํางานช้าๆ หลังจากนั้น

หมายเหตุ

Webhooks เป็นเพียงความสะดวก ไม่ใช่การรับประกันถ้าการส่งงานพลาด GET /v1/job/{id} จะมีสถานะปัจจุบันของการเรนเดอร์เสมอ

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

วิธีการ	เส้นทาง	สิ่งที่มันทํา
GET	/api/webhooks/events	แสดงชื่อเหตุการณ์และรูปแบบลายเซ็น
GET	/api/webhooks/hooks	แสดงรายการเว็บฮุคของคุณ
POST	/api/webhooks/hooks	สร้างเว็บฮุก
PATCH	/api/webhooks/hooks/{id}	หยุดชั่วคราว ดําเนินการต่อ หรือเปลี่ยน URL หรือคําอธิบาย
DELETE	/api/webhooks/hooks/{id}	ลบเว็บฮุก
POST	/api/webhooks/hooks/{id}/test	ส่ง pingที่ลงนาม

บัญชีหนึ่งสามารถมีเว็บฮุกได้สูงสุด 25 ตัวรูปแบบคําขอและการตอบกลับเต็มรูปแบบอยู่ในจุดอ้างอิงปลายทาง