Webhooks

Un webhook informe votre serveur quand quelque chose se produit, comme la fin d’une vidéo. Il vous évite de faire des sondages GET /v1/job/{id}. Les webhooks sont gérés avec la même clé API que le reste du API, sous https://reigniter.ai/api/webhooks.

Événements

Événement	Envoyé quand
video.completed	Rendu terminé. La charge utile a download_url, un lien qui fonctionne pendant 7 jours.
video.failed	Un rendu a échoué. Un rendu que vous annulez n’envoie pas ceci.
training.invited	Un apprenant se voyait attribuer un module et recevoir sa page de formation.
training.completed	Un apprenant nommé terminait un module. La charge utile contient le score (indiqué par le serveur), passed, et leur page de résultats.
training.passed / training.failed	Envoyé avec training.completed, contre la note de passage du module. Le temps qui manque est un échec.
training.overdue	Un apprenant n’a pas terminé avant sa date limite. Une fois par invitation.
training.certificate_expiring	Un certificat expire dans les 30 jours. Une fois par certificat.
post.published	Un article a été publié sur YouTube, TikTok, LinkedIn, Facebook ou Instagram. La charge utile contient la plateforme, le compte et url, le lien vers le post lorsque la plateforme en fournit un.
post.failed	Un article ne pouvait pas être publié. reason est la réponse de la plateforme en termes simples.
credits.low	Le solde est tombé à 10 crédits ou moins. Une fois par drop.
credits.purchased	Des crédits ont été ajoutés au compte.
subscription.created	Un abonnement a été lancé.
subscription.canceled	Un abonnement au forfait a été annulé.
user.signup	Le compte a été créé.
user.onboarded	Le compte a terminé son intégration.

GET /api/webhooks/events renvoie cette liste.

Installez un webhook

1. Construisez un point de terminaison sur votre serveur qui accepte les requêtes POST avec un corps JSON et répond rapidement 2xx. Il doit être accessible sur Internet public. Les adresses réseau privées et locales sont refusées.

2. Abonnez-le à un événement. Un webhook écoute un événement ; créez-en un par événement dont vous avez besoin.

   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. Stockez les secret de la réponse 201. Vous en avez besoin pour vérifier les signatures.

   Attention

   Le secret de signature est montré une fois. Les lectures ultérieures retournent has_secret: true à la place. Si vous le perdez, supprimez le webhook et créez-le à nouveau.

4. Envoyez un test. POST /api/webhooks/hooks/{id}/test envoie un événement ping signé à votre URL et vous indique ce que votre point de terminaison a répondu :

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

Souscrire à nouveau le même événement et la même URL ne crée pas de doublon. Il renvoie le webhook existant avec reused: true et le rallume.

À quoi ressemble une livraison

Chaque livraison est une POST avec un corps 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 transporte job_id, user_id, canvas_id et un reason.

Associez payload.job_id à la job_id que vous avez reçue de POST /v1/render.

Et ces en-têtes :

En-tête	Valeur
X-Reigniter-Event	Le nom de l’événement.
X-Reigniter-Delivery	Un identifiant unique pour cette livraison. Elle reste la même lorsque la livraison est retentie.
X-Reigniter-Timestamp	Heure Unix, en secondes, lorsque la livraison a été signée.
X-Reigniter-Signature	sha256= et le hexadécime HMAC-SHA256 de {timestamp}.{raw body}, liés à votre secret.

Vérifiez la signature

Vérifiez chaque livraison avant de lui faire confiance :

1. Lisez le corps brut de la demande, avant toute JSON analyse synctique.
2. Construis la chaîne {X-Reigniter-Timestamp}.{raw body}.
3. Calculez HMAC-SHA256 avec votre secret, en hexadécime, et ajoutez sha256= devant.
4. Comparez-le avec X-Reigniter-Signature en utilisant une comparaison en temps constant.
5. Refusez la livraison si l’horodatage a plus de 5 minutes.

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)

Livraison et essais

• Chaque livraison attend jusqu’à 10 secondes que votre point de terminaison réponde.
• Un 5xx, un 429, un délai d’attente ou une erreur réseau est retenté, jusqu’à 3 tentatives au total, à environ une seconde d’intervalle.
• Tout autre 4xx n’est pas repris.
• Les essais restent les mêmes X-Reigniter-Delivery. Utilisez-le pour ignorer une livraison que vous avez déjà traitée.
• Après 20 livraisons ratées d’affilée, le webhook est désactivé. GET /api/webhooks/hooks affiche active: false et la dernière erreur dans last_status. Corrigez votre point de terminaison, puis réactivez-le avec PATCH /api/webhooks/hooks/{id} et { "active": true }.

Répondez 2xx dès que vous avez stocké la livraison, puis faites un travail lent ensuite.

Note

Les webhooks sont une commodité, pas une garantie. Si une livraison est manquée, GET /v1/job/{id} a toujours l’état actuel d’un rendu.

Gérer les webhooks

Méthode	Chemin	Ce que ça fait
GET	/api/webhooks/events	Listez les noms des événements et le schéma de signature
GET	/api/webhooks/hooks	Listez vos webhooks
POST	/api/webhooks/hooks	Créer un webhook
PATCH	/api/webhooks/hooks/{id}	Mettre en pause, reprendre ou modifier l’URL ou la description
DELETE	/api/webhooks/hooks/{id}	Supprimer un webhook
POST	/api/webhooks/hooks/{id}/test	Envoyez un ping signé

Un compte peut avoir jusqu’à 25 webhooks. Les formes complètes de requête et de réponse se trouvent dans la référence du point de terminaison.