Webhooki

Webhook informuje serwer, gdy coś się dzieje, na przykład gdy wideo się kończy. Oszczędza to ankiety GET /v1/job/{id}. Webhooki są zarządzane tym samym API kluczem co reszta API, pod https://reigniter.ai/api/webhooks.

Wydarzenia

Wydarzenie	Wysłano, gdy
video.completed	Renderowanie zakończone. Ładunek zawiera download_url, link, który działa przez 7 dni.
video.failed	Renderowanie się nie powiodło. Render, który anulujesz, nie wysyła tego.
training.invited	Uczestnikowi przydzielono moduł i przesłano mu stronę szkoleniową.
training.completed	Nazwany uczący się ukończył moduł. Ładunek zawiera wynik (oznaczony przez serwer), passed oraz stronę z wynikami.
training.passed / training.failed	Wysłane z training.completed, co jest zgodne z zaliczeniem modułu. Koniec czasu to porażka.
training.overdue	Uczący się nie skończył oddania do terminu. Raz na zaproszenie.
training.certificate_expiring	Certyfikat wygasa w ciągu 30 dni. Raz na certyfikat.
post.published	Post został opublikowany na YouTube, TikTok, LinkedIn, Facebook lub Instagram. Payload zawiera platformę, konto i url, link do posta, gdy platforma go podaje.
post.failed	Post nie mógł zostać opublikowany. reason jest prostą odpowiedzią platformy.
credits.low	Saldo spadło do 10 kredytów lub mniej. Raz na drop.
credits.purchased	Na konto dodano kredyty.
subscription.created	Rozpoczęto subskrypcję planu.
subscription.canceled	Anulowano subskrypcję planu.
user.signup	Konto zostało utworzone.
user.onboarded	Konto zakończyło onboarding.

GET /api/webhooks/events zwraca tę listę.

Ustaw webhook

1. Zbuduj na serwerze endpoint, który akceptuje POST żądania z JSON body i odpowiada 2xx szybko. Musi być dostępny w publicznym internecie. Prywatne i lokalne adresy sieciowe są odrzucane.

2. Zasubskrybuj wydarzenie. Jeden webhook odsłuchuje jedno wydarzenie; stwórz taki na każde potrzebne wydarzenie.

   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. Przechowuj secret z odpowiedzi 201. Potrzebujesz go do sprawdzania podpisów.

   Uwaga

   Sekret podpisu jest pokazany raz. Później czytaj powrót has_secret: true zamiast tego. Jeśli go zgubisz, usuń webhook i utwórz go ponownie.

4. Wyślij test. POST /api/webhooks/hooks/{id}/test wysyła podpisane zdarzenie ping na Twój adres URL i informuje, na co odpowiedział Twój punkt:

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

Subskrybowanie tego samego zdarzenia i adresu URL ponownie nie tworzy duplikatu. Zwraca istniejący webhook z reused: true i włącza go ponownie.

Jak wygląda dostawa

Każda poród to POST z JSON ciałem:

{
  "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 niesie job_id, user_id, canvas_id oraz reason.

Dopasuj payload.job_id do job_id, które dostałeś od POST /v1/render.

A te nagłówki:

Nagłówek	Wartość
X-Reigniter-Event	Nazwa wydarzenia.
X-Reigniter-Delivery	Unikalny identyfikator dla tej dostawy. Pozostaje taki sam po ponownej próbie dostawy.
X-Reigniter-Timestamp	Czas Unix, w sekundach, gdy dostawa została podpisana.
X-Reigniter-Signature	sha256= i heks HMAC-SHA256 z {timestamp}.{raw body}, powiązany z twoim sekretem.

Sprawdź podpis

Sprawdź każdą dostawę, zanim jej zaufasz:

1. Przeczytaj surowy treść żądania, zanim JSON cokolwiek analizujesz.
2. Buduj strunę {X-Reigniter-Timestamp}.{raw body}.
3. Oblicz HMAC-SHA256 z twoim sekretem jako heks, a sha256= przed nim.
4. Porównaj to z X-Reigniter-Signature za pomocą porównania w czasie stałym.
5. Odrzucić dostawę, jeśli znacznik czasu jest starszy niż 5 minut.

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)

Dostarczanie i ponowne próby

• Każda dostawa czeka do 10 sekund na odpowiedź punktu końcowego.
• Powtarza się 5xx, 429, timeout lub błąd sieciowy, łącznie do 3 prób, co około sekundy.
• Inne 4xx nie są powtarzane.
• Próby powtórek zachowują ten sam X-Reigniter-Delivery. Użyj go, aby zignorować dostawę, którą już obsłużyłeś.
• Po 20 nieudanych dostawach z rzędu webhook zostaje wyłączony. GET /api/webhooks/hooks pokazuje active: false i ostatni błąd w last_status. Napraw swój punkt końcowy, a następnie włącz go ponownie PATCH /api/webhooks/hooks/{id} i { "active": true }.

Odpowiedz 2xx zaraz po przechowaniu dostawy, a potem wykonuj powolną pracę.

Notatka

Webhooki są wygodą, a nie gwarancją. Jeśli dostawa zostanie przegapiona, zawsze GET /v1/job/{id} pokazuje aktualny stan renderowania.

Zarządzaj webhookami

Metoda	Ścieżka	Co robi
GET	/api/webhooks/events	Nazwy zdarzeń i schemat sygnatury
GET	/api/webhooks/hooks	Wystaw swoje webhooki
POST	/api/webhooks/hooks	Stwórz webhook
PATCH	/api/webhooks/hooks/{id}	Zatrzymaj się, wznow lub zmień adres URL lub opis
DELETE	/api/webhooks/hooks/{id}	Usuń webhook
POST	/api/webhooks/hooks/{id}/test	Wyślij podpisany ping

Konto może mieć do 25 webhooków. Pełne kształty żądań i odpowiedzi znajdują się w referencji końcowej.