Webhooks

Webhook, bir video bitişi gibi bir şey olduğunda sunucunuza bildirir. Anket GET /v1/job/{id} tasarruf eder. Webhooklar, diğer API ile aynı API anahtarı ile yönetilir, https://reigniter.ai/api/webhooks altında.

Etkinlikler

Etkinlik	Gönderildiğinde
video.completed	Bir render tamamlandı. Yükün download_url var, 7 gün çalışan bir bağlantı.
video.failed	Bir render başarısız oldu. İptal ettiğiniz bir render bunu göndermez.
training.invited	Bir öğrenene bir modül atanıyor ve eğitim sayfası gönderiliyordu.
training.completed	Isimli bir öğrenci bir modülü tamamladı. Yük, sunucu tarafından işaretlenen puan, passed ve sonuçlar sayfasını içerir.
training.passed / training.failed	Modülün geçiş işaretine karşı training.completed ile gönderildi. Zamanın bitmesi başarısızlıktır.
training.overdue	Bir öğrenci teslim tarihine kadar bitirmemiştir. Davetiye başına bir kez.
training.certificate_expiring	Sertifika 30 gün içinde geçerliliğini kaybeder. Her sertifika için bir kez.
post.published	Bir gönderi YouTube, TikTok, LinkedIn, Facebook veya Instagramüzerinden yayınlanmıştır. Yük platform, hesap ve url, platform verdiğinde gönderiye bağlantı içerir.
post.failed	Bir gönderi yayınlanamazdı. reason platformun açık sözlü cevabıdır.
credits.low	Bakiye 10 krediye veya daha azına düştü. Her düşüşte bir kere.
credits.purchased	Hesaba krediler eklendi.
subscription.created	Bir plan aboneliği başladı.
subscription.canceled	Bir plan aboneliği iptal edildi.
user.signup	Hesap oluşturuldu.
user.onboarded	Hesap işe başlamayı tamamladı.

GET /api/webhooks/events bu listeyi geri döndürüyor.

Bir web kancası kur

1. Sunucunuza, POST talepleri kabul eden ve JSON gövdeli bir uç nokta oluştur ve 2xx hızlıca yanıt ver. Halka açık internet üzerinden ulaşılabilir olmalıdır. Özel ve yerel ağ adresleri reddedilir.

2. Bir etkinliğe abone olun. Bir web hook bir etkinliği dinler; ihtiyacınız olan her etkinliğe bir tane oluşturun.

   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. 201 yanıtındaki secret sakla. İmzaları kontrol etmek için buna ihtiyacınız var.

   Dikkat

   İmza sırrı bir kez gösterilir. Daha sonraki okumalar has_secret: true geri döner. Kaybederseniz, web kancasını silin ve tekrar oluşturun.

4. Bir test gönderin. POST /api/webhooks/hooks/{id}/test, URL’nize imzalı bir ping olayı gönderir ve uç noktanızın ne yanıtladığını size bildirir:

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

Aynı etkinliği ve URL’yi tekrar abone etmek bir çoğaltma oluşturmaz. Mevcut web kancasını reused: true ile döndürür ve tekrar açar.

Teslimat nasıl görünüyor

Her teslimat JSON bir gövdeye sahip bir POST:

{
  "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 ve bir reason taşır.

payload.job_id POST /v1/render’den aldığın job_id ile eşleştir.

Ve bu başlıklar:

Başlık	Değer
X-Reigniter-Event	Etkinlik adı.
X-Reigniter-Delivery	Bu teslimat için benzersiz bir ID. Teslimat tekrar denendiğinde aynı kalır.
X-Reigniter-Timestamp	Unix zamanı, teslimatın imzalandığı saniyelerde.
X-Reigniter-Signature	sha256= ve {timestamp}.{raw body}’in HMAC-SHA256 büyüsü, sırrınızla bağlantılı.

İmzayı doğrulayın

Her teslimatı güvenmeden önce kontrol edin:

1. Ham istek gövdesini okuyun, JSON ayrıştırmadan önce.
2. Teli {X-Reigniter-Timestamp}.{raw body} yap.
3. Sırrınızla HMAC-SHA256’yı hex olarak hesaplayın ve önüne sha256= ekleyin.
4. Sabit zamanlı bir karşılaştırma kullanarak X-Reigniter-Signature ile karşılaştırın.
5. Zaman damgası 5 dakikadan fazla eskiyse teslimatı reddedin.

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)

Teslimat ve tekrar denemeler

• Her teslimat, uç noktanızın cevap vermesi için 10 saniyeye kadar beklenir.
• Bir 5xx, bir 429, bir zaman aşımı veya ağ hatası tekrar denenir, toplamda yaklaşık bir saniye arayla 3 denemeye kadar.
• Başka hiçbir 4xx tekrar denenmez.
• Tekrar denemeler aynı X-Reigniter-Delivery tutuyor. Zaten ellediğiniz bir teslimatı görmezden gelmek için kullanın.
• Üst üste 20 başarısız teslimattan sonra web kancası kapanıyor. GET /api/webhooks/hooks active: false ve son hatayı last_status gösteriyor. Uç noktanızı düzeltin, sonra PATCH /api/webhooks/hooks/{id} ile tekrar açın ve { "active": true }.

Teslimatı depolayın 2xx cevap verin ve sonrasında yavaş çalışın.

Not

Webhooklar bir kolaylıktır, garanti değil. Bir teslimat kaçırılırsa, GET /v1/job/{id} her zaman renderın mevcut durumuna sahiptir.

Webhookları yönet

Yöntem	Yol	Ne yapar
GET	/api/webhooks/events	Olay isimlerini ve imza şemasını listeleyin
GET	/api/webhooks/hooks	Webhooklarınızı listeleyin
POST	/api/webhooks/hooks	Bir web kancası oluşturun
PATCH	/api/webhooks/hooks/{id}	URL veya açıklamayı duraklat, devam ettir veya değiştir
DELETE	/api/webhooks/hooks/{id}	Bir web kancasını sil
POST	/api/webhooks/hooks/{id}/test	İmzalı bir ping gönderin

Bir hesapta 25’e kadar web kancası olabilir. Tam istek ve yanıt şekilleri uç nokta referansında bulunur.