Przykłady webhooków

Ta strona zawiera kompletne, gotowe do produkcji przykłady odbierania i przetwarzania webhooków Ignite w różnych językach programowania.

Pełne przykłady serwera

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
}

Dostawy webhooków

Każda próba dostarczenia webhooka jest logowana. Jeśli dostawa się nie powiedzie, system automatycznie ponowi próbę.

Status dostawy

Status	Opis
`success`	Zdarzenie zostało dostarczone pomyślnie (odpowiedź HTTP 2xx)
`failed`	Dostawa nie powiodła się (timeout, HTTP 4xx/5xx, błąd sieci)

Informacje o dostawie

Każdy wpis o dostawie zawiera:

Pole	Opis
`responseCode`	Kod statusu HTTP zwrócony przez Twój endpoint
`responseBody`	Treść odpowiedzi z Twojego endpointu (obcięta przy dużych odpowiedziach)
`errorMessage`	Komunikat błędu, jeśli dostawa się nie powiodła
`deliveredAt`	Znacznik czasu próby dostawy
`attemptNumber`	Która to próba (rosnie przy ponowieniach)
`nextRetryAt`	Kiedy zaplanowano następne ponowienie (jeśli dotyczy)

Zachowanie przy ponowieniach

Nieudane dostawy są automatycznie ponawiane
Jeśli ustawiono nextRetryAt, ponowienie jest zaplanowane
Jeśli nextRetryAt nie jest ustawione, kolejnych ponowień nie będzie

Dobre praktyki

Stosowanie tych praktyk zwiększa niezawodność przetwarzania webhooków i ułatwia diagnozowanie problemów.

Czas odpowiedzi

Twój endpoint musi odpowiedzieć w ciągu 30 sekund. Przy długo trwających operacjach od razu potwierdź odbiór webhooka i przetwarzaj asynchronicznie:


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
}

Bezpieczeństwo

Chroń sekrety — nigdy nie umieszczaj sekretu podpisywania w kodzie po stronie klienta ani w repozytorium
Używaj HTTPS — w produkcji zawsze endpointów HTTPS
Weryfikuj wszystko — zawsze sprawdzaj podpisy przed przetwarzaniem
Ograniczanie częstotliwości — rozważ limitowanie żądań na swoim endpoincie

Niezawodność

Idempotentność — zapisuj i sprawdzaj X-Webhook-Delivery-Id, żeby obsłużyć duplikaty dostaw
Logowanie — loguj wszystkie żądania webhooków do debugowania
Monitoring — ustaw alerty na nieudane przetwarzanie webhooków
Obsługa błędów — zwracaj odpowiednie kody HTTP, żeby ponowienia działały poprawnie

Kody statusu HTTP

Kod	Znaczenie
`200-299`	Sukces — zdarzenie przetworzone
`4xx`	Błąd po stronie klienta — będzie ponowione
`5xx`	Błąd serwera — będzie ponowione

Rozwiązywanie problemów

Brak zdarzeń

Sprawdź, czy subskrypcja webhooka ma status Active
Zweryfikuj, czy wybrane są właściwe typy zdarzeń
Upewnij się, że zdarzenia występują we właściwej przestrzeni roboczej
Sprawdź logi serwera pod kątem przychodzących żądań

Weryfikacja podpisu się nie udaje

Upewnij się, że używasz właściwego sekretu podpisywania (a nie tokena API)
Sprawdź, czy treść żądania nie jest modyfikowana przed weryfikacją
Sprawdź zgodność serializacji JSON (zwarta, bez zbędnych spacji)
Sprawdź, czy nagłówek podpisu jest parsowany poprawnie: t=timestamp,v1=signature

Błędy timeoutu

Odpowiadaj w ciągu 30 sekund
Przenieś długie operacje do przetwarzania w tle
Zwróć od razu 200, przetwarzaj asynchronicznie

Zduplikowane zdarzenia

Wprowadź idempotentność z użyciem X-Webhook-Delivery-Id
Sprawdzaj attemptNumber przy ponowieniach
Przechowuj przetworzone identyfikatory dostaw w bazie danych