Webhooks

Een webhook vertelt je server wanneer er iets gebeurt, zoals een video die wordt afgesloten. Het bespaart je polling GET /v1/job/{id}. Webhooks worden beheerd met dezelfde API sleutel als de rest van de API, onder https://reigniter.ai/api/webhooks.

Evenementen

Evenement	Verzonden wanneer
video.completed	Een render voltooid. De payload heeft download_url, een link die 7 dagen werkt.
video.failed	Een render mislukte. Een render die je annuleert stuurt dit niet.
training.invited	Een leerling kreeg een module toegewezen en stuurde zijn trainingspagina toe.
training.completed	Een benoemde leerling heeft een module afgerond. De payload bevat de score (gemarkeerd door de server), passed, en hun resultatenpagina.
training.passed / training.failed	Verzonden met training.completed, tegen het voldoende cijfer van de module. Tijd tekortkomen is een onvoldoende.
training.overdue	Een leerling is niet klaar op de deadline. Eén keer per uitnodiging.
training.certificate_expiring	Een certificaat verloopt binnen 30 dagen. Eén keer per certificaat.
post.published	Een bericht ging live op YouTube, TikTok, LinkedIn, Facebook of Instagram. De payload bevat het platform, het account en url, de link naar het bericht wanneer het platform die geeft.
post.failed	Een bericht kon niet worden gepubliceerd. reason is het antwoord van het platform in eenvoudige woorden.
credits.low	Het saldo daalde tot 10 credits of minder. Eén keer per drop.
credits.purchased	Er werden tegoeden aan het account toegevoegd.
subscription.created	Er is een abonnementsabonnement gestart.
subscription.canceled	Een abonnementsabonnement werd opgezegd.
user.signup	Het account is aangemaakt.
user.onboarded	Het account is afgerond met de onboarding.

GET /api/webhooks/events geeft deze lijst terug.

Zet een webhook op

1. Bouw een endpoint op je server dat POST verzoeken accepteert met een JSON body en 2xx snel beantwoordt. Het moet bereikbaar zijn op het publieke internet. Private en lokale netwerkadressen worden geweigerd.

2. Abonneer je op een evenement. Eén webhook luistert naar één evenement; maak er één voor elk evenement dat je nodig hebt.

   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. Sla de secret uit de 201 reactie op. Je hebt het nodig om handtekeningen te controleren.

   Opgepast

   Het signeergeheim wordt één keer getoond. Latere lezingen keren has_secret: true terug. Als je het verliest, verwijder dan de webhook en maak het opnieuw aan.

4. Stuur een test. POST /api/webhooks/hooks/{id}/test stuurt een ondertekend ping-event naar je URL en vertelt je wat je endpoint heeft beantwoord:

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

Het opnieuw abonneren op hetzelfde event en dezelfde URL creëert geen duplicaat. Het retourneert de bestaande webhook met reused: true en zet deze weer aan.

Hoe een levering eruitziet

Elke levering is een POST met een JSON lichaam:

{
  "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 draagt job_id, user_id, canvas_id en een reason.

Koppel payload.job_id aan de job_id die je van POST /v1/render hebt gekregen.

En deze koppen:

Kopstuk	Waarde
X-Reigniter-Event	De naam van het evenement.
X-Reigniter-Delivery	Een unieke ID voor deze levering. Het blijft hetzelfde wanneer een levering opnieuw wordt geprobeerd.
X-Reigniter-Timestamp	Unix-tijd, in seconden, wanneer de levering werd ondertekend.
X-Reigniter-Signature	sha256= en de hex HMAC-SHA256 van {timestamp}.{raw body}, gekoppeld aan jouw geheim.

Controleer de handtekening

Controleer elke levering voordat je het vertrouwt:

1. Lees de raw request-tekst, voordat je JSON ontleedt.
2. Bouw de snaar {X-Reigniter-Timestamp}.{raw body}.
3. Bereken HMAC-SHA256 daarvan met je geheim als hex en voeg sha256= ervoor.
4. Vergelijk het met X-Reigniter-Signature met een constante tijdvergelijking.
5. Weiger de levering als de tijdstempel ouder is dan 5 minuten.

JavaScript

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

export function verifyReigniterWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-banshea-timestamp'];
  const received = headers['x-banshea-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)

Levering en herpogingen

• Elke levering wacht tot 10 seconden tot je endpoint antwoordt.
• Een 5xx, een 429, een timeout of een netwerkfout wordt opnieuw geprobeerd, tot 3 pogingen in totaal, ongeveer een seconde uit elkaar.
• Elke andere 4xx wordt niet opnieuw geprobeerd.
• Herkansingen houden dezelfde X-Reigniter-Delivery. Gebruik het om een levering die je al hebt afgehandeld te negeren.
• Na 20 mislukte leveringen op rij wordt de webhook uitgeschakeld. GET /api/webhooks/hooks toont active: false en de laatste fout in last_status. Fix je endpoint en zet het dan weer aan met PATCH /api/webhooks/hooks/{id} en { "active": true }.

Beantwoord 2xx zodra je de levering hebt opgeslagen, en doe daarna langzaam werk.

Opmerking

Webhooks zijn een gemak, geen garantie. Als een levering wordt gemist, heeft GET /v1/job/{id} altijd de huidige staat van een render.

Beheer webhooks

Methode	Pad	Wat het doet
GET	/api/webhooks/events	Lijst evenementnamen en het handtekeningschema
GET	/api/webhooks/hooks	Zet je webhooks op
POST	/api/webhooks/hooks	Maak een webhook
PATCH	/api/webhooks/hooks/{id}	Pauzeer, hervat of wijzig de URL of beschrijving
DELETE	/api/webhooks/hooks/{id}	Verwijder een webhook
POST	/api/webhooks/hooks/{id}/test	Stuur een ondertekende ping

Een account kan tot 25 webhooks hebben. Volledige verzoek- en responsvormen staan in de endpointreferentie.