Skip to main content

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

Webhook Security

Request Signing

All webhook requests include a signature header:

Signature Verification

Webhook Payload

Standard Payload Structure

Event-Specific Data

Each event type includes relevant data:

media.moderated

test.webhook

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

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