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
- Navigate to your site settings
- Enter your webhook endpoint URL
- Generate or enter a webhook secret
- Select events to receive
- 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:- Initial attempt: Immediate
- First retry: After 1 minute
- Second retry: After 5 minutes
- Third retry: After 30 minutes
- 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
- Test endpoint: Use webhook testing tools
- Local development: Use ngrok or similar
- Verify signatures: Test signature validation
- Handle errors: Test error scenarios
Best Practices
Implementation
- Quick Response: Respond within 30 seconds
- Async Processing: Queue events for processing
- Idempotency: Handle duplicate events
- Error Handling: Gracefully handle failures
Security
- Verify Signatures: Always validate requests
- Use HTTPS: Require secure connections
- IP Allowlisting: Restrict to known IPs
- Rate Limiting: Protect against abuse
Reliability
- Acknowledge Quickly: Return 200 immediately
- Process Async: Handle events in background
- Log Everything: Track all webhook activity
- Monitor Health: Alert on failures
Related Concepts
- Webhook API - API reference
- Webhook Integration - Setup tutorial
- Sites - Site webhook configuration