Production Webhook Handler

This guide covers production-ready webhook handlers with error handling, logging, and best practices.

New to webhooks? Start with our Webhook Quickstart for a complete end-to-end tutorial.

Production Requirements

Your production webhook handler should:

✅ Handle POST requests with JSON payloads
✅ Return 2xx status codes for successful processing
✅ Acknowledge promptly after verifying and durably accepting the event
✅ Handle retries gracefully (deduplicate repeated deliveries)
✅ Log events for debugging and monitoring
✅ Verify signatures for security

Retry Behavior

Automatic Retries: Network failures, timeouts, and non-2xx responses cause Magic Hour to schedule another delivery attempt:

Pattern: Scheduled delays of 1, 2, 4, 8, … minutes, capped at 60 minutes
Expiry: Events more than 24 hours old are marked as failed and are no longer delivered
Security headers: The timestamp and signature are regenerated for each delivery attempt

These are scheduled delays, not guaranteed delivery times. The expiry is measured from event creation, not the first failed attempt. Disabled Webhooks: Pending events are rescheduled without delivery and retain the same expiry. Re-enabling the webhook allows pending deliveries to resume before expiry.

Production Handler Examples

These examples omit signature verification. Before accepting events, verify the signature and timestamp against the raw body. Save the verified event to a database or durable queue before returning 2xx. A restart can lose in-process background tasks after Magic Hour considers delivery complete.

from fastapi import FastAPI, Request, HTTPException, BackgroundTasks
from sqlalchemy.orm import Session
from datetime import datetime
import logging
import json
import time

app = FastAPI()
logger = logging.getLogger(__name__)

@app.post("/webhook")
async def webhook_handler(
    request: Request,
    background_tasks: BackgroundTasks
):
    try:
        # Get event data
        event = await request.json()
        event_type = event.get('type')
        payload = event.get('payload', {})

        # Log the event
        logger.info(f"Received webhook: {event_type}", extra={
            'event_type': event_type,
            'job_id': payload.get('id'),
            'status': payload.get('status')
        })

        # Process in background to respond quickly
        background_tasks.add_task(process_webhook_event, event)

        return {"success": True, "timestamp": int(time.time())}

    except Exception as e:
        logger.error(f"Webhook processing failed: {str(e)}")
        raise HTTPException(status_code=500, detail="Internal server error")

async def process_webhook_event(event: dict):
    """Process webhook event in background"""
    try:
        event_type = event['type']
        payload = event['payload']
        job_id = payload['id']

        # Update database record
        with get_db_session() as db:
            job = db.query(Job).filter(Job.magic_hour_id == job_id).first()
            if not job:
                logger.warning(f"Job {job_id} not found in database")
                return

            if event_type == 'video.completed':
                job.status = 'completed'
                job.download_url = payload['downloads'][0]['url']
                job.completed_at = datetime.utcnow()

                # Notify user (email, push notification, etc.)
                await notify_user_completion(job.user_id, job)

            elif event_type == 'video.errored':
                job.status = 'failed'
                job.error_message = payload['error']['message']
                job.failed_at = datetime.utcnow()

                # Notify user of failure
                await notify_user_error(job.user_id, job)

            db.commit()
            logger.info(f"Updated job {job_id} status to {job.status}")

    except Exception as e:
        logger.error(f"Background processing failed: {str(e)}")

const express = require("express");
const redis = require("redis");
const { createLogger, format, transports } = require("winston");

const app = express();
const redisClient = redis.createClient();

// Setup logging
const logger = createLogger({
  level: "info",
  format: format.combine(format.timestamp(), format.errors({ stack: true }), format.json()),
  transports: [new transports.File({ filename: "webhook.log" }), new transports.Console()],
});

app.use(express.json());

app.post("/webhook", async (req, res) => {
  try {
    const { type, payload } = req.body;
    const jobId = payload.id;

    // Log the event
    logger.info("Received webhook", {
      eventType: type,
      jobId: jobId,
      status: payload.status,
    });

    // Respond immediately
    res.status(200).json({
      success: true,
      timestamp: Math.floor(Date.now() / 1000),
    });

    // Process asynchronously
    processWebhookEvent(type, payload);
  } catch (error) {
    logger.error("Webhook processing failed", { error: error.message });
    res.status(500).json({ error: "Internal server error" });
  }
});

async function processWebhookEvent(type, payload) {
  try {
    const jobId = payload.id;

    // Update job status in Redis
    const jobKey = `job:${jobId}`;

    switch (type) {
      case "video.started":
        await redisClient.hSet(jobKey, {
          status: "processing",
          startedAt: new Date().toISOString(),
        });
        break;

      case "video.completed":
        await redisClient.hSet(jobKey, {
          status: "completed",
          downloadUrl: payload.downloads[0].url,
          completedAt: new Date().toISOString(),
        });

        // Notify user via WebSocket, email, etc.
        await notifyUserCompletion(jobId, payload);
        break;

      case "video.errored":
        await redisClient.hSet(jobKey, {
          status: "failed",
          error: JSON.stringify(payload.error),
          failedAt: new Date().toISOString(),
        });

        await notifyUserError(jobId, payload);
        break;
    }

    logger.info(`Updated job ${jobId} status`, { type, status: payload.status });
  } catch (error) {
    logger.error("Background processing failed", { error: error.message });
  }
}

const port = process.env.PORT || 8000;
app.listen(port, () => {
  logger.info(`Webhook server running on port ${port}`);
});

Best Practices

1. Deduplicate Webhook Deliveries

Magic Hour may retry delivery, so detect and skip repeated events:

# Webhook payloads don't include an event ID, so build a dedup key
# from the project ID and event type
dedup_key = f"{event['payload']['id']}:{event['type']}"

if await is_event_processed(dedup_key):
    logger.info(f"Event {dedup_key} already processed, skipping")
    return {"success": True}

# Process event and mark as processed
await process_event(event)
await mark_event_processed(dedup_key)

Use an atomic database claim or unique constraint for the deduplication key so concurrent deliveries cannot both process it. Apply job-state changes transactionally and avoid replacing a terminal state with a delayed started event.

2. Quick Response Times

Acknowledge promptly after signature verification and durable acceptance. Run long processing from the saved event. The abbreviated timing examples below do not implement those production requirements:

# ✅ Good: Respond immediately, process in background
@app.post("/webhook")
async def webhook(request: Request, background_tasks: BackgroundTasks):
    event = await request.json()
    background_tasks.add_task(process_event, event)
    return {"success": True}  # Respond immediately

# ❌ Bad: Long processing blocks response
@app.post("/webhook")
async def webhook(request: Request):
    event = await request.json()
    await long_running_process(event)  # This might timeout
    return {"success": True}

3. Comprehensive Logging

Log all events for debugging:

logger.info("Webhook received", extra={
    'event_type': event['type'],
    'job_id': event['payload']['id'],
    'timestamp': int(time.time()),
    'user_agent': request.headers.get('user-agent'),
    'ip_address': request.client.host
})

4. Error Handling

Handle errors gracefully:

try:
    await process_webhook(event)
except ValidationError as e:
    logger.error(f"Invalid webhook data: {e}")
    return {"error": "Invalid data"}, 400
except Exception as e:
    logger.error(f"Webhook processing failed: {e}")
    return {"error": "Internal error"}, 500

Local Testing

Test your handler locally before deploying:

# Start your server
uvicorn main:app --reload --port 8000

# In another terminal, send test event
curl -X POST http://localhost:8000/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "type": "video.completed",
    "payload": {
      "id": "test-job-123",
      "status": "complete",
      "downloads": [
        {
          "url": "https://example.com/video.mp4",
          "expires_at": "2024-12-01T12:00:00Z"
        }
      ]
    }
  }'

# Start your server
node server.js

# In another terminal, send test event
curl -X POST http://localhost:8000/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image.completed",
    "payload": {
      "id": "test-job-456",
      "status": "complete",
      "downloads": [
        {
          "url": "https://example.com/image.png",
          "expires_at": "2024-12-01T12:00:00Z"
        }
      ]
    }
  }'

Deployment Considerations

Load Balancing

If using multiple servers, ensure webhooks can reach any instance:

# docker-compose.yml
services:
  webhook-handler:
    image: your-webhook-app
    replicas: 3
    ports:
      - "8000-8002:8000"

Health Checks

Add a health check endpoint:

@app.get("/health")
async def health_check():
    return {"status": "healthy", "timestamp": int(time.time())}

Monitoring

Monitor webhook delivery and processing:

# Track metrics
webhook_counter = Counter('webhooks_received_total', ['event_type'])
processing_time = Histogram('webhook_processing_seconds')

@app.post("/webhook")
async def webhook(request: Request):
    start_time = time.time()
    event = await request.json()

    webhook_counter.labels(event_type=event['type']).inc()

    # Process event...

    processing_time.observe(time.time() - start_time)
    return {"success": True}

Next Steps

Secure Your Handler

Add signature verification for production security

Event Types Reference

Complete list of webhook events and payloads

Webhook API Reference

Detailed webhook API documentation

Quickstart Guide

New to webhooks? Start with our quickstart

Common Issues

Webhook timeouts?

Return 2xx promptly after signature verification and durable acceptance
Process long-running work from a durable queue or saved event, not only in-process background tasks
Check server resources and scaling

Missing events?

Verify webhook is enabled in Developer Hub
Check endpoint URL is correct and accessible
Review server logs for errors

Duplicate events?

Deduplicate deliveries using the project ID and event type
Store processed deduplication keys
Handle retries gracefully

Need help? Contact support@magichour.ai

Get Started

Integration

Billing

Tools

Production Requirements

Retry Behavior

Production Handler Examples

Best Practices

1. Deduplicate Webhook Deliveries

2. Quick Response Times

3. Comprehensive Logging

4. Error Handling

Local Testing

Deployment Considerations

Load Balancing

Health Checks

Monitoring

Next Steps

Secure Your Handler

Event Types Reference

Webhook API Reference

Quickstart Guide

Common Issues

​Production Requirements

​Retry Behavior

​Production Handler Examples

​Best Practices

​1. Deduplicate Webhook Deliveries

​2. Quick Response Times

​3. Comprehensive Logging

​4. Error Handling

​Local Testing

​Deployment Considerations

​Load Balancing

​Health Checks

​Monitoring

​Next Steps

Secure Your Handler

Event Types Reference

Webhook API Reference

Quickstart Guide

​Common Issues

Production Requirements

Retry Behavior

Production Handler Examples

Best Practices

1. Deduplicate Webhook Deliveries

2. Quick Response Times

3. Comprehensive Logging

4. Error Handling

Local Testing

Deployment Considerations

Load Balancing

Health Checks

Monitoring

Next Steps

Common Issues