​
Overview

Webhooks provide real-time notifications when moderation events occur. They enable your application to react immediately to content decisions without polling for updates.

​
Webhook Events

​
Available Events

media.created

Triggered when new media is submitted for moderation

media.moderated

Triggered when moderation is complete

test.webhook

Test event for webhook verification

​
Webhook Configuration

​
Setting Up Webhooks

  1. Navigate to your site settings
  2. Enter your webhook endpoint URL
  3. Generate or enter a webhook secret
  4. Select events to receive
  5. Save configuration

​
Configuration Example

{
  "url": "https://your-app.com/webhooks/pixel-patrol",
  "secret": "your-webhook-secret-key",
  "events": ["media.created", "media.moderated"],
  "active": true
}

​
Webhook Security

​
Request Signing

All webhook requests include a signature header: 
X-PixelPatrol-Signature: 3f3d7c4b5e6789abcdef1234567890abcdef1234567890abcdef1234567890ab
X-PixelPatrol-Timestamp: 1705745400000
X-PixelPatrol-Event: media.moderated

​
Signature Verification

import { createHmac } from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return expected === signature;
}

​
Webhook Payload

​
Standard Payload Structure

{
  "id": "webhook_123",
  "event": "media.moderated",
  "created_at": "2024-01-20T10:30:00Z",
  "data": {
    "media_id": "media_456",
    "site_id": "site_789",
    "status": "approved",
    "ai_results": {
      "labels": []
    },
    "applied_rules": []
  }
}

​
Event-Specific Data

Each event type includes relevant data:

​
media.moderated

{
  "media_id": "media_456",
  "status": "approved|rejected|flagged",
  "ai_results": {},
  "applied_rules": [],
  "moderated_at": "2024-01-20T10:30:00Z"
}

​
test.webhook

{
  "media_id": "test_456",
  "status": "test",
  "is_test": true,
  "message": "Test webhook received successfully"
}

​
Delivery & Reliability

​
Delivery Guarantees

  • At-least-once delivery: Webhooks may be sent multiple times
  • Ordered delivery: Events are sent in chronological order
  • Idempotency: Use event IDs to handle duplicates

​
Retry Logic

Failed webhook deliveries are retried:
  1. Initial attempt: Immediate
  2. First retry: After 1 minute
  3. Second retry: After 5 minutes
  4. Third retry: After 30 minutes
  5. Final retry: After 2 hours

​
Failure Handling

Webhooks fail when:
  • HTTP status code is not 2xx
  • Request times out (30 seconds)
  • Connection errors occur
  • SSL/TLS errors

​
Implementation Guide

​
Basic Webhook Handler

import express from 'express';

const app = express();

app.post('/webhooks/pixel-patrol', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-pixelpatrol-signature'];
  const payload = req.body.toString();
  
  // Verify signature
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  
  // Handle event
  switch (event.event) {
    case 'media.moderated':
      handleMediaModerated(event.data);
      break;
    case 'test.webhook':
      console.log('Test webhook received');
      break;
  }
  
  // Acknowledge receipt
  res.status(200).send('OK');
});

​
Monitoring & Debugging

​
Webhook Logs

View webhook delivery attempts:
  • Delivery status
  • Response codes
  • Response times
  • Error messages

​
Testing Webhooks

  1. Test endpoint: Use webhook testing tools
  2. Local development: Use ngrok or similar
  3. Verify signatures: Test signature validation
  4. Handle errors: Test error scenarios

​
Best Practices

​
Implementation

  1. Quick Response: Respond within 30 seconds
  2. Async Processing: Queue events for processing
  3. Idempotency: Handle duplicate events
  4. Error Handling: Gracefully handle failures

​
Security

  1. Verify Signatures: Always validate requests
  2. Use HTTPS: Require secure connections
  3. IP Allowlisting: Restrict to known IPs
  4. Rate Limiting: Protect against abuse

​
Reliability

  1. Acknowledge Quickly: Return 200 immediately
  2. Process Async: Handle events in background
  3. Log Everything: Track all webhook activity
  4. Monitor Health: Alert on failures