Esempi di webhook

Questa pagina offre esempi completi e pronti per la produzione per ricevere ed elaborare i webhook Ignite in diversi linguaggi di programmazione.

Esempi di server completi

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
}

Consegne webhook

Ogni tentativo di consegna webhook viene registrato. Se una consegna fallisce, il sistema riprova automaticamente.

Stato della consegna

Stato	Descrizione
`success`	Evento consegnato con successo (risposta HTTP 2xx)
`failed`	Consegna fallita (timeout, HTTP 4xx/5xx, errore di rete)

Informazioni sulla consegna

Ogni record di consegna contiene:

Campo	Descrizione
`responseCode`	Codice di stato HTTP restituito dal tuo endpoint
`responseBody`	Corpo della risposta del tuo endpoint (troncato per risposte grandi)
`errorMessage`	Messaggio di errore se la consegna è fallita
`deliveredAt`	Timestamp del tentativo di consegna
`attemptNumber`	Numero del tentativo (si incrementa con i retry)
`nextRetryAt`	Quando verrà tentato il prossimo retry (se applicabile)

Comportamento dei retry

Le consegne fallite vengono riprovate automaticamente
Se nextRetryAt è impostato, è pianificato un retry
Se nextRetryAt non è impostato, non verranno effettuati altri retry

Buone pratiche

Seguire queste buone pratiche garantisce un’elaborazione affidabile dei webhook e aiuta a risolvere i problemi.

Tempo di risposta

Il tuo endpoint deve rispondere entro 30 secondi. Per operazioni lunghe, conferma subito la ricezione del webhook ed elabora in modo asincrono:


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
}

Sicurezza

Proteggi i segreti — Non esporre mai il signing secret nel codice lato client o nel controllo versione
Usa HTTPS — In produzione usa sempre endpoint HTTPS
Valida tutto — Verifica sempre le firme prima di elaborare
Rate limiting — Valuta di applicare il rate limiting sul tuo endpoint

Affidabilità

Idempotenza — Memorizza e controlla X-Webhook-Delivery-Id per gestire consegne duplicate
Logging — Registra tutte le richieste webhook per il debug
Monitoraggio — Imposta avvisi per elaborazioni webhook fallite
Gestione errori — Restituisci codici di stato HTTP appropriati così i retry funzionano correttamente

Codici di stato HTTP

Codice	Significato
`200-299`	Successo — evento elaborato
`4xx`	Errore client — verrà riprovato
`5xx`	Errore server — verrà riprovato

Risoluzione dei problemi

Nessun evento ricevuto

Controlla che la sottoscrizione webhook sia impostata su Active
Verifica che siano selezionati i tipi di evento corretti
Assicurati che gli eventi avvengano nel workspace corretto
Controlla i log del server per le richieste in arrivo

La verifica della firma fallisce

Verifica di usare il signing secret corretto (non un token API)
Assicurati che il corpo della richiesta non venga modificato prima della verifica
Controlla che la serializzazione JSON coincida (compatta, senza spazi extra)
Verifica che il formato dell’intestazione firma sia analizzato correttamente: t=timestamp,v1=signature

Errori di timeout

Rispondi entro 30 secondi
Sposta le operazioni lunghe in elaborazione in background
Restituisci subito 200, elabora in modo asincrono

Eventi duplicati

Implementa l’idempotenza usando X-Webhook-Delivery-Id
Controlla attemptNumber per i retry
Memorizza gli ID di consegna elaborati in un database