Webhooks

Webhook thông báo cho máy chủ của bạn khi có sự cố xảy ra, chẳng hạn như video kết thúc. Nó giúp bạn tiết kiệm việc kiểm tra GET /v1/job/{id}. Webhook được quản lý bằng cùng một khóa API như phần còn lại của API, theo https://reigniter.ai/api/webhooks.

Sự kiện

Sự kiện	Gửi khi
video.completed	Một bản render đã hoàn thành. Payload có download_url, một liên kết hoạt động trong 7 ngày.
video.failed	Một render đã thất bại. Một render bạn hủy sẽ không gửi được thông tin này.
training.invited	Một học viên được giao một mô-đun và gửi trang đào tạo của họ.
training.completed	Một học viên được chỉ định đã hoàn thành một mô-đun. Payload có điểm số (được máy chủ đánh dấu), passed và trang kết quả của họ.
training.passed / training.failed	Gửi với training.completed, trái với điểm đậu của mô-đun. Hết thời gian là trượt.
training.overdue	Người học chưa hoàn thành đúng hạn. Một lần cho mỗi lời mời.
training.certificate_expiring	Một chứng chỉ hết hạn trong vòng 30 ngày. Mỗi chứng chỉ một lần.
post.published	Một bài đăng đã được đăng trên YouTube, TikTok, LinkedIn, Facebook hoặc Instagram. Payload có nền tảng, tài khoản và url, liên kết đến bài đăng khi nền tảng cung cấp.
post.failed	Không thể đăng bài đăng. reason là câu trả lời của nền tảng bằng những lời đơn giản.
credits.low	Số dư giảm xuống còn 10 tín dụng hoặc ít hơn. Một lần cho mỗi lần rơi.
credits.purchased	Các khoản tín dụng được cộng vào tài khoản.
subscription.created	Một gói đăng ký đã bắt đầu.
subscription.canceled	Một gói đăng ký đã bị hủy.
user.signup	Tài khoản đã được tạo.
user.onboarded	Tài khoản đã hoàn tất quá trình onboarding.

GET /api/webhooks/events trả về danh sách này.

Thiết lập webhook

1. Xây dựng một điểm cuối trên máy chủ của bạn chấp nhận các yêu cầu POST với thân JSON và trả lời 2xx nhanh chóng. Nó phải có thể truy cập được trên internet công cộng. Địa chỉ mạng riêng tư và cục bộ sẽ bị từ chối.

2. Đăng ký một sự kiện. Một webhook nghe một sự kiện; tạo một webhook cho mỗi sự kiện bạn cần.

   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. Lưu secret từ phản hồi 201. Bạn cần nó để kiểm tra chữ ký.

   Chú ý

   Bí mật ký được hiển thị một lần. Các lần đọc sau sẽ trả về has_secret: true thay thế. Nếu bạn mất nó, hãy xóa webhook và tạo lại.

4. Gửi một bài kiểm thử. POST /api/webhooks/hooks/{id}/test gửi một sự kiện ping đã ký đến URL của bạn và cho bạn biết kết quả của điểm cuối đã trả lời:

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

Đăng ký lại cùng một sự kiện và URL không tạo ra bản sao. Nó trả về webhook hiện có với reused: true và bật lại.

Giao hàng trông như thế nào

Mỗi lần giao hàng là một POST với thân 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 mang job_id, user_id, canvas_id và một reason.

So sánh payload.job_id với job_id bạn nhận được từ POST /v1/render.

Và các tiêu đề sau:

Tiêu đề	Giá trị
X-Reigniter-Event	Tên sự kiện.
X-Reigniter-Delivery	Một ID duy nhất cho đơn hàng này. Nó sẽ giữ nguyên khi một lần giao hàng được thử lại.
X-Reigniter-Timestamp	Thời gian Unix, tính bằng giây, khi giao hàng được ký.
X-Reigniter-Signature	sha256= và hex HMAC-SHA256 của {timestamp}.{raw body}, được khóa với bí mật của bạn.

Xác minh chữ ký

Kiểm tra từng đơn hàng trước khi tin tưởng:

1. Hãy đọc phần thân yêu cầu thô trước khi JSON phân tích cú pháp.
2. Xây dựng chuỗi {X-Reigniter-Timestamp}.{raw body}.
3. Tính toán HMAC-SHA256 của nó với bí mật của bạn, dưới dạng lục giác, rồi thêm sha256= ở phía trước.
4. So sánh với X-Reigniter-Signature bằng cách so sánh thời gian hựng số.
5. Từ chối giao hàng nếu dấu thời gian đã quá 5 phút.

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)

Giao hàng và thử lại

• Mỗi lần giao hàng sẽ chờ tối đa 10 giây để điểm cuối trả lời.
• Một lần 5xx, một 429, timeout hoặc lỗi mạng được thử lại, tối đa 3 lần thử, cách nhau khoảng một giây.
• Bất kỳ 4xx nào khác sẽ không được thử lại.
• Các lần thử lại giữ nguyên X-Reigniter-Delivery. Dùng nó để bỏ qua một đơn hàng bạn đã xử lý.
• Sau 20 lần giao hàng thất bại liên tiếp, webhook sẽ tắt. GET /api/webhooks/hooks hiển thị lỗi active: false và lỗi cuối cùng trong last_status. Sửa điểm cuối của bạn, sau đó bật lại bằng PATCH /api/webhooks/hooks/{id} và { "active": true }.

Trả lời 2xx ngay khi bạn đã lưu trữ giao hàng, rồi làm việc chậm rãi sau đó.

Ghi chú

Webhook chỉ là tiện lợi, không phải đảm bảo. Nếu giao hàng bị bỏ lỡ, GET /v1/job/{id} luôn giữ trạng thái hiện tại của bản render.

Quản lý webhook

Phương pháp	Đường đi	Nó làm gì
GET	/api/webhooks/events	Liệt kê tên sự kiện và sơ đồ chữ ký
GET	/api/webhooks/hooks	Liệt kê webhook của bạn
POST	/api/webhooks/hooks	Tạo webhook
PATCH	/api/webhooks/hooks/{id}	Tạm dừng, tiếp tục hoặc thay đổi URL hoặc mô tả
DELETE	/api/webhooks/hooks/{id}	Xóa webhook
POST	/api/webhooks/hooks/{id}/test	Gửi ping đã ký

Một tài khoản có thể có tối đa 25 webhook. Các hình yêu cầu và phản hồi đầy đủ nằm trong tham chiếu điểm cuối.