Webhook

Webhook memberi tahu server Anda saat sesuatu terjadi, seperti video selesai. Webhook menghemat Anda dari GET /v1/job/{id} polling. Webhook dikelola dengan kunci API yang sama seperti API lainnya, di bawah https://reigniter.ai/api/webhooks.

Acara

Acara	Dikirim saat
video.completed	Render selesai. Payload memiliki download_url, sebuah tautan yang bekerja selama 7 hari.
video.failed	Sebuah render gagal. Render yang Anda batalkan tidak mengirimkan ini.
training.invited	Seorang peserta didik diberikan modul dan mengirimkan halaman pelatihan mereka.
training.completed	Seorang peserta bernama menyelesaikan modul. Payload berisi skor (ditandai oleh server), passed, dan halaman hasilnya.
training.passed / training.failed	Dikirim dengan training.completed, dengan tanda lulus modul. Kehabisan waktu adalah kegagalan.
training.overdue	Seorang peserta belum selesai pada tanggal jatuh tempo. Sekali per undangan.
training.certificate_expiring	Sertifikat berakhir dalam waktu 30 hari. Sekali per sertifikat.
post.published	Sebuah postingan disiarkan di YouTube, TikTok, LinkedIn, Facebook, atau Instagram. Payload berisi platform, akun, dan url, tautan ke postingan saat platform memberikannya.
post.failed	Sebuah postingan tidak dapat dipublikasikan. reason adalah jawaban platform ini secara sederhana.
credits.low	Saldo turun menjadi 10 kredit atau kurang. Sekali per tetes.
credits.purchased	Kredit ditambahkan ke akun.
subscription.created	Langganan paket dimulai.
subscription.canceled	Langganan paket dibatalkan.
user.signup	Akun tersebut telah dibuat.
user.onboarded	Akun selesai proses onboarding.

GET /api/webhooks/events mengembalikan daftar ini.

Siapkan webhook

1. Bangun endpoint di server Anda yang menerima permintaan POST dengan body JSON dan menjawab 2xx dengan cepat. Endpoint tersebut harus dapat diakses melalui internet publik. Alamat jaringan privat dan lokal ditolak.

2. Berlangganan ke sebuah acara. Satu webhook mendengarkan satu acara; buat satu per acara yang Anda butuhkan.

   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. Simpan secret dari respons 201. Anda membutuhkannya untuk memeriksa tanda tangan.

   Perhatian

   Rahasia penandatanganan ditampilkan sekali. Bacaan berikutnya mengembalikan has_secret: true sebagai gantinya. Jika Anda kehilangannya, hapus webhook dan buat lagi.

4. Kirim tes. POST /api/webhooks/hooks/{id}/test mengirimkan event ping yang ditandatangani ke URL Anda dan memberi tahu apa yang dijawab endpoint Anda:

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

Berlangganan event dan URL yang sama tidak akan menghasilkan duplikat. Webhook yang ada akan kembali menggunakan reused: true dan mengaktifkannya kembali.

Seperti apa sebuah pengiriman

Setiap pengiriman adalah POST dengan tubuh 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 membawa job_id, user_id, canvas_id, dan reason.

Cocokkan payload.job_id dengan job_id yang kamu dapat dari POST /v1/render.

Dan header-header berikut:

Header	Nilai
X-Reigniter-Event	Nama acara.
X-Reigniter-Delivery	ID unik untuk pengiriman ini. Identitas tetap sama saat pengiriman dicoba ulang.
X-Reigniter-Timestamp	Waktu Unix, dalam hitungan detik, saat pengiriman ditandatangani.
X-Reigniter-Signature	sha256= dan HMAC-SHA256 heksagon dari {timestamp}.{raw body}, dikunci dengan rahasiamu.

Verifikasi tanda tangan

Periksa setiap pengiriman sebelum Anda mempercayainya:

1. Baca isi permintaan mentah, sebelum melakukan parsing JSON.
2. Bangun string {X-Reigniter-Timestamp}.{raw body}.
3. Hitung HMAC-SHA256 dengan secret Anda, sebagai hex, dan tambahkan sha256= di depan.
4. Bandingkan dengan X-Reigniter-Signature menggunakan perbandingan waktu konstan.
5. Tolak pengiriman jika stempel waktu sudah lebih dari 5 menit.

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)

Pengiriman dan percobaan ulang

• Setiap pengiriman menunggu hingga 10 detik untuk endpoint Anda merespons.
• Sebuah 5xx, 429, timeout, atau kesalahan jaringan dicoba ulang, hingga total 3 percobaan, sekitar satu detik terpisah.
• 4xx lain tidak akan diuji ulang.
• Upaya ulang mempertahankan X-Reigniter-Delivery yang sama. Gunakan untuk mengabaikan pengiriman yang sudah Anda tangani.
• Setelah 20 pengiriman gagal berturut-turut, webhook dimatikan. GET /api/webhooks/hooks menunjukkan active: false dan kesalahan terakhir di last_status. Perbaiki endpoint Anda, lalu aktifkan kembali dengan PATCH /api/webhooks/hooks/{id} dan { "active": true }.

Jawab 2xx segera setelah Anda menyimpan pengiriman, dan lakukan pekerjaan perlahan setelahnya.

Catatan

Webhook adalah kemudahan, bukan jaminan. Jika pengiriman terlewat, GET /v1/job/{id} selalu memiliki status render saat ini.

Kelola webhook

Metode	Jalur	Apa yang dilakukan
GET	/api/webhooks/events	Daftar nama event dan skema tanda tangan
GET	/api/webhooks/hooks	Daftarkan webhook Anda
POST	/api/webhooks/hooks	Buat webhook
PATCH	/api/webhooks/hooks/{id}	Jeda, lanjutkan, atau ubah URL atau deskripsi
DELETE	/api/webhooks/hooks/{id}	Hapus webhook
POST	/api/webhooks/hooks/{id}/test	Kirim ping yang ditandatangani

Sebuah akun dapat memiliki hingga 25 webhook. Bentuk permintaan dan respons lengkap ada di referensi endpoint.