Exemples de webhooks

Cette page propose des exemples complets, prêts pour la production, pour recevoir et traiter les webhooks Ignite dans différents langages de programmation.

Exemples serveur complets

Next.js API Routes


// pages/api/webhook.ts
import { createHmac, timingSafeEqual } from "crypto";
import { NextApiRequest, NextApiResponse } from "next";
 
// Disable body parser to access raw body for signature verification
export const config = {
  api: {
    bodyParser: false,
  },
};
 
interface ThumbnailFormat {
  url: string;
  fileSize: number;
}
 
interface ThumbnailVariant {
  name: string;
  width: number;
  height: number;
  formats: {
    jpeg: ThumbnailFormat;
    webp: ThumbnailFormat;
  };
}
 
interface VideoWebhookData {
  id: string;
  status: "COMPLETE" | "PROCESSING" | "NO_FILE" | "FAILED";
  title: string;
  src?: {
    thumbnails?: ThumbnailVariant[];
    thumbnailUrl?: string; // deprecated — use src.thumbnails instead
    mp4?: Array<{ name: string; url: string; width: number; height: number }>;
  };
  // ... other video properties
}
 
async function getRawBody(req: NextApiRequest): Promise<string> {
  const chunks: Buffer[] = [];
  for await (const chunk of req) {
    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
  }
  return Buffer.concat(chunks).toString("utf-8");
}
 
function isValidSignature(
  rawBody: string,
  signatureHeader: string | string[] | undefined,
  secret: string
): boolean {
  try {
    if (typeof signatureHeader !== "string") {
      return false;
    }
 
    const time = signatureHeader.match(/t=(\d+)/)?.[1];
    const token = signatureHeader.match(/v1=(\w+)/)?.[1];
 
    if (!time || !token) {
      return false;
    }
 
    const signedPayload = `${time}.${rawBody}`;
    const hmac = createHmac("sha256", secret);
    const calculatedSignature = hmac.update(signedPayload).digest("hex");
 
    return timingSafeEqual(
      Buffer.from(token),
      Buffer.from(calculatedSignature)
    );
  } catch {
    return false;
  }
}
 
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== "POST") {
    return res.status(405).end();
  }
 
  const rawBody = await getRawBody(req);
 
  if (
    !isValidSignature(
      rawBody,
      req.headers["x-webhook-signature"],
      process.env.WEBHOOK_SIGNING_SECRET!
    )
  ) {
    console.error("Invalid webhook signature");
    return res.status(403).end();
  }
 
  const eventType = req.headers["x-webhook-event"];
  const deliveryId = req.headers["x-webhook-delivery-id"];
  const video = JSON.parse(rawBody) as VideoWebhookData;
 
  // Process based on event type
  switch (eventType) {
    case "video.created":
      console.log("New video created:", video.id, video.title);
      // await handleVideoCreated(video);
      break;
 
    case "video.updated":
      console.log("Video updated:", video.id, video.title);
      if (video.status === "COMPLETE") {
        // Video processing finished - update your database
        // await db.updateVideo(video.id, {
        //   thumbnails: video.src?.thumbnails,
        //   thumbnail: video.src?.thumbnails?.[0]?.formats.jpeg.url,
        //   sizes: video.src?.mp4,
        // });
      }
      break;
 
    case "video.deleted":
      console.log("Video deleted:", video.id);
      // await handleVideoDeleted(video);
      break;
  }
 
  return res.status(204).end();
}

Express.js


const express = require('express');
const crypto = require('crypto');
 
const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SIGNING_SECRET;
 
// Parse JSON and preserve raw body for signature verification
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf.toString();
  }
}));
 
function verifyWebhookSignature(rawBody, signatureHeader, secret) {
  const parts = signatureHeader.split(',');
  const timestampPart = parts.find(p => p.startsWith('t='));
  const signaturePart = parts.find(p => p.startsWith('v1='));
  
  if (!timestampPart || !signaturePart) {
    return false;
  }
  
  const timestamp = timestampPart.split('=')[1];
  const receivedSignature = signaturePart.split('=')[1];
  
  // Reconstruct signed payload using raw body
  const signedPayload = `${timestamp}.${rawBody}`;
  const hmac = crypto.createHmac('sha256', secret);
  const calculatedSignature = hmac.update(signedPayload).digest('hex');
  
  try {
    return crypto.timingSafeEqual(
      Buffer.from(receivedSignature),
      Buffer.from(calculatedSignature)
    );
  } catch {
    return false;
  }
}
 
// Store processed delivery IDs (use a database in production)
const processedDeliveries = new Set();
 
app.post('/webhook', async (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const eventType = req.headers['x-webhook-event'];
  const deliveryId = req.headers['x-webhook-delivery-id'];
  
  // 1. Verify signature
  if (!verifyWebhookSignature(req.rawBody, signature, WEBHOOK_SECRET)) {
    console.error('Invalid webhook signature');
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // 2. Check for duplicate deliveries (idempotency)
  if (processedDeliveries.has(deliveryId)) {
    console.log('Duplicate delivery, skipping:', deliveryId);
    return res.status(200).json({ received: true, duplicate: true });
  }
  
  // 3. Get video data from body
  const video = req.body;
  
  // 4. Process based on event type
  try {
    switch(eventType) {
      case 'video.created':
        console.log('New video created:', video.id, video.title);
        await handleVideoCreated(video);
        break;
        
      case 'video.updated':
        console.log('Video updated:', video.id, video.title);
        await handleVideoUpdated(video);
        break;
        
      case 'video.deleted':
        console.log('Video deleted:', video.id);
        await handleVideoDeleted(video);
        break;
        
      default:
        console.log('Unknown event type:', eventType);
    }
    
    // Mark as processed
    processedDeliveries.add(deliveryId);
    
    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Error processing webhook:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});
 
// Event handlers
async function handleVideoCreated(video) {
  // Example: Sync to your CMS
  // await cms.createVideo({
  //   externalId: video.id,
  //   title: video.title,
  //   status: video.status
  // });
}
 
async function handleVideoUpdated(video) {
  // Example: Update your CMS when video processing completes
  // if (video.status === 'COMPLETE') {
  //   await cms.updateVideo(video.id, {
  //     streamUrl: video.src.abr.url,
  //     thumbnails: video.src.thumbnails,
  //     thumbnail: video.src.thumbnails[0].formats.jpeg.url,
  //     duration: video.duration
  //   });
  // }
}
 
async function handleVideoDeleted(video) {
  // Example: Remove from your CMS
  // await cms.deleteVideo(video.id);
}
 
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook endpoint listening on port ${PORT}`);
});

Python / Flask


from flask import Flask, request, jsonify
import hmac
import hashlib
import os
 
app = Flask(__name__)
WEBHOOK_SECRET = os.environ.get('WEBHOOK_SIGNING_SECRET')
 
# Store processed delivery IDs (use a database in production)
processed_deliveries = set()
 
def verify_webhook_signature(raw_body, signature_header, secret):
    parts = signature_header.split(',')
    timestamp_part = next((p for p in parts if p.startswith('t=')), None)
    signature_part = next((p for p in parts if p.startswith('v1=')), None)
    
    if not timestamp_part or not signature_part:
        return False
    
    timestamp = timestamp_part.split('=')[1]
    received_signature = signature_part.split('=')[1]
    
    # Calculate expected signature using raw body
    signed_payload = f"{timestamp}.{raw_body}"
    calculated_signature = hmac.new(
        secret.encode('utf-8'),
        signed_payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(received_signature, calculated_signature)
 
 
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature')
    event_type = request.headers.get('X-Webhook-Event')
    delivery_id = request.headers.get('X-Webhook-Delivery-Id')
    raw_body = request.get_data(as_text=True)
    
    # 1. Verify signature
    if not verify_webhook_signature(raw_body, signature, WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401
    
    # 2. Check for duplicate deliveries
    if delivery_id in processed_deliveries:
        return jsonify({'received': True, 'duplicate': True}), 200
    
    # 3. Get video data
    video = request.json
    
    # 4. Process based on event type
    try:
        if event_type == 'video.created':
            print(f"New video created: {video.get('id')} - {video.get('title')}")
            handle_video_created(video)
            
        elif event_type == 'video.updated':
            print(f"Video updated: {video.get('id')} - {video.get('title')}")
            handle_video_updated(video)
            
        elif event_type == 'video.deleted':
            print(f"Video deleted: {video.get('id')}")
            handle_video_deleted(video)
        
        else:
            print(f"Unknown event type: {event_type}")
        
        # Mark as processed
        processed_deliveries.add(delivery_id)
        
        return jsonify({'received': True}), 200
        
    except Exception as e:
        print(f"Error processing webhook: {e}")
        return jsonify({'error': 'Internal server error'}), 500
 
 
def handle_video_created(video):
    # Example: Sync to your CMS
    pass
 
 
def handle_video_updated(video):
    # Example: Update CMS when processing completes
    if video.get('status') == 'COMPLETE':
        # Update with stream URLs, thumbnail, duration, etc.
        pass
 
 
def handle_video_deleted(video):
    # Example: Remove from your CMS
    pass
 
 
if __name__ == '__main__':
    app.run(port=3000, debug=True)

PHP


<?php
require 'vendor/autoload.php';
 
$webhookSecret = getenv('WEBHOOK_SIGNING_SECRET');
 
function verifyWebhookSignature($rawBody, $signatureHeader, $secret) {
    $parts = explode(',', $signatureHeader);
    $timestamp = null;
    $receivedSignature = null;
    
    foreach ($parts as $part) {
        if (strpos($part, 't=') === 0) {
            $timestamp = substr($part, 2);
        } elseif (strpos($part, 'v1=') === 0) {
            $receivedSignature = substr($part, 3);
        }
    }
    
    if (!$timestamp || !$receivedSignature) {
        return false;
    }
    
    $signedPayload = $timestamp . '.' . $rawBody;
    $calculatedSignature = hash_hmac('sha256', $signedPayload, $secret);
    
    return hash_equals($calculatedSignature, $receivedSignature);
}
 
// Get request data
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$eventType = $_SERVER['HTTP_X_WEBHOOK_EVENT'] ?? '';
$deliveryId = $_SERVER['HTTP_X_WEBHOOK_DELIVERY_ID'] ?? '';
 
// Set JSON response header
header('Content-Type: application/json');
 
// 1. Verify signature
if (!verifyWebhookSignature($rawBody, $signature, $webhookSecret)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}
 
// 2. Parse body
$video = json_decode($rawBody, true);
 
// 3. Process based on event type
try {
    switch ($eventType) {
        case 'video.created':
            error_log("New video created: {$video['id']} - {$video['title']}");
            handleVideoCreated($video);
            break;
            
        case 'video.updated':
            error_log("Video updated: {$video['id']} - {$video['title']}");
            handleVideoUpdated($video);
            break;
            
        case 'video.deleted':
            error_log("Video deleted: {$video['id']}");
            handleVideoDeleted($video);
            break;
            
        default:
            error_log("Unknown event type: {$eventType}");
    }
    
    http_response_code(200);
    echo json_encode(['received' => true]);
    
} catch (Exception $e) {
    error_log("Error processing webhook: " . $e->getMessage());
    http_response_code(500);
    echo json_encode(['error' => 'Internal server error']);
}
 
function handleVideoCreated($video) {
    // Example: Sync to your CMS
}
 
function handleVideoUpdated($video) {
    // Example: Update CMS when processing completes
    if ($video['status'] === 'COMPLETE') {
        // Update with stream URLs, thumbnail, duration, etc.
    }
}
 
function handleVideoDeleted($video) {
    // Example: Remove from your CMS
}

Livraisons webhook

Chaque tentative de livraison d’un webhook est journalisée. Si une livraison échoue, le système retente automatiquement.

Statut de livraison

Statut	Description
`success`	Événement livré avec succès (réponse HTTP 2xx)
`failed`	Échec de la livraison (délai dépassé, HTTP 4xx/5xx, erreur réseau)

Informations de livraison

Chaque enregistrement de livraison contient :

Champ	Description
`responseCode`	Code de statut HTTP renvoyé par ton endpoint
`responseBody`	Corps de la réponse de ton endpoint (tronqué si trop volumineux)
`errorMessage`	Message d’erreur en cas d’échec de livraison
`deliveredAt`	Horodatage de la tentative de livraison
`attemptNumber`	Numéro de la tentative (s’incrémente aux nouvelles tentatives)
`nextRetryAt`	Date de la prochaine tentative (le cas échéant)

Comportement des nouvelles tentatives

Les livraisons en échec sont automatiquement retentées
Si nextRetryAt est défini, une nouvelle tentative est planifiée
Si nextRetryAt n’est pas défini, aucune nouvelle tentative n’aura lieu

Bonnes pratiques

Suivre ces bonnes pratiques assure un traitement fiable des webhooks et facilite le débogage.

Temps de réponse

Ton endpoint doit répondre dans les 30 secondes. Pour des opérations longues, accuse réception immédiatement du webhook et traite en arrière-plan :


app.post('/webhook', async (req, res) => {
  // Immediately acknowledge receipt
  res.status(200).json({ received: true });
  
  // Process asynchronously (don't await)
  processWebhookAsync(req.body).catch(console.error);
});
 
async function processWebhookAsync(video) {
  // Long-running operations here
}

Sécurité

Secrets — N’expose jamais ton secret de signature dans le code client ni dans le contrôle de version
HTTPS — Utilise toujours des endpoints HTTPS en production
Validation — Vérifie toujours les signatures avant traitement
Limitation de débit — Envisage une limitation de débit sur ton endpoint

Fiabilité

Idempotence — Stocke et vérifie X-Webhook-Delivery-Id pour gérer les livraisons en double
Journaux — Journalise toutes les requêtes webhook pour le débogage
Surveillance — Configure des alertes en cas d’échec du traitement
Gestion d’erreurs — Renvoie des codes HTTP appropriés pour que les nouvelles tentatives fonctionnent

Codes de statut HTTP

Code	Signification
`200-299`	Succès — événement traité
`4xx`	Erreur client — nouvelle tentative prévue
`5xx`	Erreur serveur — nouvelle tentative prévue

Dépannage

Aucun événement reçu

Vérifie que l’abonnement webhook est actif
Vérifie que les bons types d’événements sont sélectionnés
Assure-toi que les événements se produisent dans le bon espace de travail
Consulte les journaux de ton serveur pour les requêtes entrantes

Échec de la vérification de signature

Vérifie que tu utilises le bon secret de signature (pas un jeton d’API)
Assure-toi que le corps de la requête n’est pas modifié avant la vérification
Vérifie que la sérialisation JSON correspond (compacte, sans espace superflu)
Vérifie que le format de l’en-tête de signature est correctement analysé : t=timestamp,v1=signature

Erreurs de délai dépassé

Réponds dans les 30 secondes
Déplace les opérations longues vers un traitement en arrière-plan
Renvoie 200 immédiatement, traite de façon asynchrone

Événements en double

Implémente l’idempotence avec X-Webhook-Delivery-Id
Consulte attemptNumber pour les nouvelles tentatives
Stocke les ID de livraison traités en base de données