Debugging Tools
Webhook Logs: Dashboard → Settings → Webhooks → View Logs
Test Webhook: Send test payload to verify endpoint is working
Request Logs: Check recent webhook attempts, responses, and errors
Retry History: View failed deliveries and retry attempts
Common Issues
Webhooks Not Being Received
Common Causes:
- • Endpoint URL is incorrect or unreachable
- • Firewall blocking incoming requests
- • Endpoint not using HTTPS
- • Server is down or timing out
Solutions:
Verify your endpoint URL is correct and publicly accessible
Check firewall rules allow incoming HTTPS traffic
Ensure your endpoint uses a valid SSL certificate
Check server logs for errors or timeouts
Test endpoint with curl: curl -X POST https://your-endpoint.com
Signature Verification Failing
Common Causes:
- • Using wrong webhook secret
- • Modifying request body before verification
- • Incorrect signature computation
- • Secret not properly stored in environment
Solutions:
Copy secret from webhook settings and update environment variables
Use raw request body for signature verification
Verify you're using HMAC-SHA256 with 'sha256=' prefix
Check for timing-safe comparison implementation
Test with provided example payload and secret
Webhook Timeouts
Common Causes:
- • Endpoint taking too long to respond
- • Synchronous processing of heavy operations
- • Database queries blocking response
- • External API calls delaying response
Solutions:
Respond with 200 immediately and process asynchronously
Queue webhook data for background processing
Optimize database queries and use indexes
Move external API calls to background jobs
Aim for response under 3 seconds (timeout at 5 seconds)
Receiving Duplicate Webhooks
Common Causes:
- • Endpoint not responding quickly enough
- • Network issues causing retries
- • Server returning non-200 status codes
Solutions:
Implement idempotency using event ID
Store processed event IDs in database or cache
Always respond with 200 even if event was already processed
Check for duplicate IDs before processing
Use Redis or database to track processed events
Missing Expected Events
Common Causes:
- • Webhook not subscribed to specific event types
- • Events filtered in webhook settings
- • Webhook disabled or deleted
Solutions:
Check webhook event subscriptions in settings
Verify webhook is active and enabled
Review webhook logs in dashboard
Test with 'Send Test Webhook' button
Check webhook event history for patterns
Testing Webhooks Locally
To test webhooks on your local development environment, use a tunneling service:
Using ngrok
# Install ngrok npm install -g ngrok # Start your local server (e.g., port 3000) npm run dev # In another terminal, create tunnel ngrok http 3000 # Use the HTTPS URL from ngrok as your webhook endpoint # Example: https://abc123.ngrok.io/api/webhooks/ranklite
Using Hookdeck (Alternative)
Hookdeck provides additional debugging features for webhook development:
- • Inspect webhook payloads in detail
- • Replay webhooks for testing
- • Filter and search webhook history
- • Monitor webhook performance
Debugging Checklist
Sample Curl Test
Test your endpoint manually with curl:
curl -X POST https://your-domain.com/api/webhooks/ranklite \
-H "Content-Type: application/json" \
-H "X-Ranklite-Signature: sha256=test_signature" \
-d '{
"id": "evt_test_123",
"type": "article.published",
"created": 1734134400,
"data": {
"article": {
"id": "art_test",
"title": "Test Article",
"status": "published"
}
}
}'Still Having Issues?
If you've tried these solutions and still experiencing problems, contact our support team with:
- • Your webhook endpoint URL
- • Webhook ID from settings
- • Recent error messages from logs
- • Screenshots of webhook configuration
- • Server logs showing the issue