Ejemplos de webhooks

Esta página ofrece ejemplos completos y listos para producción para recibir y procesar webhooks de Ignite en distintos lenguajes.

Ejemplos de servidor completos

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
}

Entregas de webhook

Cada intento de entrega de un webhook queda registrado. Si una entrega falla, el sistema reintentará automáticamente.

Estado de la entrega

Estado	Descripción
`success`	El evento se entregó correctamente (respuesta HTTP 2xx)
`failed`	La entrega falló (tiempo de espera agotado, HTTP 4xx/5xx, error de red)

Información de la entrega

Cada registro de entrega incluye:

Campo	Descripción
`responseCode`	Código de estado HTTP devuelto por tu endpoint
`responseBody`	Cuerpo de la respuesta de tu endpoint (truncado si es muy largo)
`errorMessage`	Mensaje de error si la entrega falló
`deliveredAt`	Marca de tiempo del intento de entrega
`attemptNumber`	Número de intento (aumenta con los reintentos)
`nextRetryAt`	Cuándo se intentará el siguiente reintegro (si aplica)

Comportamiento de reintentos

Las entregas fallidas se reintentan automáticamente
Si nextRetryAt tiene valor, hay un reintegro programado
Si nextRetryAt no tiene valor, no habrá más reintentos

Buenas prácticas

Seguir estas buenas prácticas mejora la fiabilidad del procesamiento de webhooks y facilita depurar incidencias.

Tiempo de respuesta

Tu endpoint debe responder en 30 segundos como máximo. Para operaciones largas, confirma el webhook al instante y procesa de forma asíncrona:


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
}

Seguridad

Protege los secretos — No expongas el secreto de firma en código del cliente ni en el control de versiones
Usa HTTPS — En producción, usa siempre endpoints HTTPS
Valida todo — Verifica siempre las firmas antes de procesar
Limitación de tasa — Valora aplicar rate limiting en tu endpoint

Fiabilidad

Idempotencia — Guarda y comprueba X-Webhook-Delivery-Id para gestionar entregas duplicadas
Registro — Registra todas las solicitudes de webhook para depurar
Monitorización — Configura alertas ante fallos en el procesamiento
Manejo de errores — Devuelve códigos HTTP adecuados para que los reintentos funcionen bien

Códigos de estado HTTP

Código	Significado
`200-299`	Éxito — evento procesado
`4xx`	Error de cliente — se reintentará
`5xx`	Error de servidor — se reintentará

Resolución de problemas

No recibes eventos

Comprueba que la suscripción al webhook esté activa
Verifica que los tipos de evento correctos estén seleccionados
Asegúrate de que los eventos ocurren en el espacio de trabajo correcto
Revisa los logs del servidor por solicitudes entrantes

Falla la verificación de firma

Confirma que usas el secreto de firma correcto (no un token de API)
Asegúrate de que el cuerpo de la solicitud no se modifica antes de verificar
Comprueba que la serialización JSON coincide (compacta, sin espacios extra)
Verifica que el formato de la cabecera de firma se parsea bien: t=timestamp,v1=signature

Errores de tiempo de espera

Responde en 30 segundos como máximo
Mueve las operaciones largas a procesamiento en segundo plano
Devuelve 200 de inmediato y procesa de forma asíncrona

Eventos duplicados

Implementa idempotencia con X-Webhook-Delivery-Id
Revisa attemptNumber en los reintentos
Guarda los IDs de entrega procesados en una base de datos