How to Set Up Webhook Notifications
What you'll need:
A web server capable of receiving HTTPS POST requests and basic programming knowledge to handle the webhook data.
Step 1: Create a Webhook Endpoint
First, you need to create an endpoint on your server that can receive webhook notifications. Here are examples in different programming languages:
Step 2: Make Your Endpoint Accessible
Your webhook endpoint must be accessible via HTTPS. Here are common ways to do this:
Production Deployment
- Deploy to your web server
- Use a domain with SSL certificate
- Example: https://yoursite.com/webhook
Development/Testing
- Use ngrok for local testing
- Run: ngrok http 3000
- Use the HTTPS URL provided
Step 3: Configure Webhook Channel in Tracker
- Go to your Notification Channels
- Click "Add New Channel" and select "Custom Webhook"
- Fill in the configuration:
- Webhook URL: Your HTTPS endpoint URL
- HTTP Method: POST (recommended), PUT, or PATCH
- Secret Token: A secure random string for signature verification
- API Key: Optional Bearer token for authentication
- Custom Headers: Optional additional headers as JSON
- Click "Test Configuration" to verify everything works
- Save the channel
Step 4: Handle the Webhook Data
Your webhook will receive a JSON payload with comprehensive information about the content change:
{
"event": "content_changed",
"timestamp": "2025-08-12T14:30:00Z",
"channel": {
"id": 123,
"name": "My Webhook Channel",
"type": "webhook"
},
"task": {
"id": 456,
"name": "Product Price Monitor",
"url": "https://example.com/product",
"css_path": ".price",
"content_type": "text",
"screenshot_enabled": true,
"frequency": "hourly",
"render_level": "browsershot"
},
"user": {
"id": 789,
"email": "[email protected]"
},
"notification": {
"subject": "Content Changed: Product Price Monitor",
"message": "Task: Product Price Monitor\nURL: https://example.com/product\nTime: Aug 12, 2025 at 2:30 PM\n3 content changes detected",
"is_test": false
},
"task_log": {
"id": 101112,
"content": "$29.99",
"changes": {
"changed": [
{
"path": "price",
"old_value": "$39.99",
"new_value": "$29.99"
}
],
"added": [],
"removed": []
},
"created_at": "2025-08-12T14:30:00Z"
},
"screenshot": {
"type": "url",
"url": "https://storage.tracker.com/screenshots/abc123.png",
"expires_at": "2025-08-19T14:30:00Z"
},
"metadata": {
"api_version": "1.0",
"webhook_id": "123",
"sent_at": "2025-08-12T14:30:01Z",
"user_agent": "Content-Tracker-Webhook/1.0"
}
}Security Best Practices
Important Security Considerations
- Always use HTTPS: Webhooks are only sent to HTTPS URLs for security
- Verify signatures: Use the secret token to verify webhook authenticity
- Validate input: Always validate and sanitize incoming webhook data
- Rate limiting: Implement rate limiting on your webhook endpoint
- Monitor logs: Log webhook receipts for debugging and monitoring
Advanced Configuration
Custom Headers
You can add custom headers to webhook requests:
{
"X-API-Version": "v1",
"X-Source": "content-tracker",
"Custom-Header": "your-value"
}Authentication Methods
Secret Token (Recommended)
Uses HMAC-SHA256 signature verification sent in X-Webhook-Signature header.
API Key
Sends Bearer token in Authorization header for additional authentication.
Common Use Cases
Database Logging
Store change events in your database for historical analysis
Third-party Integration
Forward notifications to other services like Zapier, IFTTT, or custom APIs
Custom Alerting
Build custom alerting logic based on change patterns and thresholds
Troubleshooting
- Verify your endpoint URL is correct and accessible
- Check that your server is running and accepting HTTPS requests
- Test your endpoint manually with curl or Postman
- Check your server logs for any errors
- Ensure your firewall allows incoming HTTPS traffic
- URL must start with https:// (HTTP is not allowed)
- Cannot point to localhost, 127.0.0.1, or private IP addresses
- Must be a publicly accessible URL
- Check for typos in the URL
- Ensure you're using the exact same secret token
- Use the raw request body for signature calculation
- Check that you're reading the X-Webhook-Signature header correctly
- Use constant-time comparison (hash_equals in PHP, hmac.compare_digest in Python)
- Webhook endpoints should respond within 30 seconds
- Process webhooks asynchronously for heavy operations
- Return a 200 status code immediately, then process
- Use queues or background jobs for time-consuming tasks
For local development and testing:
- Install ngrok: https://ngrok.com/download
- Run your webhook server locally (e.g., on port 3000)
- In another terminal: ngrok http 3000
- Use the HTTPS URL provided by ngrok in your webhook configuration
- Test using the "Test Configuration" button
Tokens Cost
Cost: Webhook notifications cost 3 tokens per notification sent.
This is in addition to the base tracking task cost.
Webhook Retry Policy
Our webhook delivery system includes automatic retries:
- Up to 3 retry attempts with exponential backoff
- Retries occur if your endpoint returns 5xx status codes or times out
- 4xx status codes (client errors) are not retried
- Successful delivery requires a 2xx status code response
Performance Tips
Do
- ✓ Respond with 200 status quickly
- ✓ Process webhooks asynchronously
- ✓ Validate webhook signatures
- ✓ Log webhook receipts
- ✓ Implement idempotency
Don't
- ✗ Perform heavy processing synchronously
- ✗ Make external API calls in webhook handler
- ✗ Ignore webhook signatures
- ✗ Return non-2xx status codes unnecessarily
- ✗ Take longer than 30 seconds to respond
Pro Tips
- Use webhooks for real-time integrations with your existing systems
- Store webhook data for audit trails and analytics
- Implement webhook replay functionality for debugging
- Use different webhook URLs for different environments (dev, staging, prod)
- Consider using webhook platforms like Svix or Hookdeck for production
Need Help?
If you're still having trouble setting up webhooks,
contact our support team
for personalized assistance.
