Overview
Webhook notifications enable real-time communication between Pixel Patrol and your application. Get instant updates on moderation decisions, system events, and more with our reliable webhook delivery system.Webhook System
Architecture
Key Features
Reliable Delivery
- Automatic retries with exponential backoff
- At-least-once delivery guarantee
- Dead letter queue for failed deliveries
Security
- HMAC-SHA256 signature verification
- TLS/SSL required endpoints
- IP allowlisting support
Performance
- Sub-second delivery times
- Parallel processing
- Rate limiting protection
Monitoring
- Detailed delivery logs
- Success/failure metrics
- Latency tracking
Event Types
Available Events
Event | Description | Payload |
---|---|---|
media.created | New media submitted | Media ID, site ID, status, timestamps |
media.moderated | Moderation complete | Status, AI results, rule evaluations |
test.webhook | Test webhook | Test data for verification |
Implementation
Webhook Endpoint
Your webhook endpoint should:Signature Verification
Delivery & Reliability
Retry Strategy
Failed webhooks are retried with exponential backoff:Attempt | Delay | Total Time |
---|---|---|
1 | Immediate | 0s |
2 | 1 minute | 1m |
3 | 5 minutes | 6m |
4 | 30 minutes | 36m |
5 | 2 hours | 2h 36m |
Failure Scenarios
Webhooks are considered failed when:- HTTP status code is not 2xx
- Connection timeout (30 seconds)
- SSL/TLS errors
- DNS resolution failures
Dead Letter Queue
After all retries fail:- Event moved to dead letter queue
- Admin notification sent
- Manual retry available
- 30-day retention
Advanced Features
Batch Webhooks
Receive multiple events in one request:Webhook Filters
Configure which events to receive:Custom Headers
Add custom headers to webhook requests:Monitoring & Debugging
Webhook Logs
Detailed logs for each delivery attempt:Health Monitoring
Track webhook health metrics:- Success Rate: Percentage of successful deliveries
- Average Latency: Time to deliver
- Queue Depth: Pending webhooks
- Error Rate: Failed delivery percentage
Testing Tools
Test Endpoint
Send test webhooks to verify setup
Webhook Inspector
View recent deliveries and payloads
Replay Events
Resend historical events
Mock Server
Test against simulated endpoints
Best Practices
Endpoint Implementation
- Quick Response: Return 200 immediately
- Async Processing: Use queues for heavy work
- Idempotency: Handle duplicate events
- Error Handling: Graceful failure recovery
Security
- Always Verify: Check signatures on every request
- Use HTTPS: Never use plain HTTP
- Validate Payloads: Sanitize input data
- Rate Limit: Protect against floods
Reliability
- Handle Retries: Expect duplicate deliveries
- Monitor Health: Track success rates
- Plan for Failures: Implement fallbacks
- Keep Logs: Retain for debugging
Troubleshooting
Common Issues
Issue | Cause | Solution |
---|---|---|
No webhooks received | Incorrect URL | Verify endpoint configuration |
Signature failures | Wrong secret | Check webhook secret |
Timeouts | Slow processing | Implement async handling |
Duplicate events | Retry mechanism | Use idempotency keys |
Debug Checklist
- Endpoint returns 2xx status
- Signature verification working
- SSL certificate valid
- No firewall blocking
- Correct event types selected
- Webhook enabled in settings
Integration Examples
Node.js/Express
Python/Flask
Related Topics
- Webhooks Concept - Core webhook concepts
- Webhook API - API reference
- Setting Up Webhooks - Setup guide