Exemplos de webhooks

Esta página oferece exemplos completos e prontos para produção para receber e processar webhooks Ignite em várias linguagens de programação.

Exemplos completos de servidor

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 tentativa de entrega de webhook é registada. Se uma entrega falhar, o sistema volta a tentar automaticamente.

Estado da entrega

Estado	Descrição
`success`	O evento foi entregue com sucesso (resposta HTTP 2xx)
`failed`	A entrega falhou (timeout, HTTP 4xx/5xx, erro de rede)

Informação da entrega

Cada registo de entrega contém:

Campo	Descrição
`responseCode`	Código de estado HTTP devolvido pelo teu endpoint
`responseBody`	Corpo da resposta do teu endpoint (truncado para respostas grandes)
`errorMessage`	Mensagem de erro se a entrega falhou
`deliveredAt`	Timestamp da tentativa de entrega
`attemptNumber`	Qual foi esta tentativa (incrementa com novas tentativas)
`nextRetryAt`	Quando será feita a próxima nova tentativa (se aplicável)

Comportamento de novas tentativas

As entregas falhadas são automaticamente repetidas
Se nextRetryAt estiver definido, fica agendada uma nova tentativa
Se nextRetryAt não estiver definido, não haverá mais novas tentativas

Boas práticas

Seguir estas boas práticas garante um processamento fiável dos webhooks e ajuda a depurar problemas.

Tempo de resposta

O teu endpoint tem de responder no prazo de 30 segundos. Para operações longas, confirma o webhook de imediato e processa de forma assí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
}

Segurança

Mantém os segredos seguros — Nunca exponhas o signing secret em código client-side ou em controlo de versões
Usa HTTPS — Usa sempre endpoints HTTPS em produção
Valida tudo — Verifica sempre as assinaturas antes de processar
Limite de pedidos — Considera implementar rate limiting no teu endpoint

Fiabilidade

Idempotência — Guarda e verifica o X-Webhook-Delivery-Id para tratar entregas duplicadas
Logging — Regista todos os pedidos de webhook para depuração
Monitorização — Configura alertas para falhas no processamento de webhooks
Tratamento de erros — Devolve códigos de estado HTTP adequados para que as novas tentativas funcionem corretamente

Códigos de estado HTTP

Código	Significado
`200-299`	Sucesso — evento processado
`4xx`	Erro do cliente — será repetido
`5xx`	Erro do servidor — será repetido

Resolução de problemas

Não recebes eventos

Verifica se a subscrição de webhook está Ativa
Confirma que os tipos de evento corretos estão selecionados
Garante que os eventos ocorrem no workspace correto
Consulta os logs do servidor à procura de pedidos recebidos

A verificação da assinatura falha

Confirma que estás a usar o signing secret correto (não um token de API)
Garante que o corpo do pedido não é alterado antes da verificação
Verifica que a serialização JSON coincide (compacta, sem espaços extra)
Confirma que o formato do cabeçalho de assinatura é analisado corretamente: t=timestamp,v1=signature

Erros de timeout

Responde no prazo de 30 segundos
Move operações longas para processamento em segundo plano
Devolve 200 de imediato e processa de forma assíncrona

Eventos duplicados

Implementa idempotência com X-Webhook-Delivery-Id
Verifica attemptNumber para novas tentativas
Guarda os IDs de entrega processados numa base de dados