Webhooks enable real-time notifications and event-driven automation. Set up webhooks to receive instant updates when tasks complete, schedules trigger, or specific conditions are met.
Webhook Events
rtrvr.ai supports various webhook events:
- task.completed - When a task finishes successfully
- task.failed - When a task encounters an error
- task.started - When a task begins execution
- schedule.triggered - When a scheduled task runs
- workflow.completed - When a sheets workflow finishes
- monitor.alert - When monitoring detects changes
Setting Up Webhooks
Configure webhooks in your dashboard or via API:
bash
POST /webhooks
{
"url": "https://your-app.com/webhook",
"events": ["task.completed", "task.failed"],
"secret": "your_webhook_secret",
"active": true
}Webhook Payload
Webhook payloads include comprehensive event data:
json
{
"event": "task.completed",
"timestamp": "2025-01-01T12:00:00Z",
"task": {
"id": "task_123",
"prompt": "Extract product prices from example.com",
"status": "completed",
"result": {
"data": [
{"product": "Widget A", "price": "$29.99"},
{"product": "Widget B", "price": "$39.99"}
],
"screenshot": "base64_image_data",
"execution_time": 15.2
}
},
"user": {
"id": "user_456",
"email": "user@example.com"
}
}Security
Webhooks include security features to verify authenticity:
- HMAC-SHA256 signatures for payload verification
- Configurable webhook secrets
- IP allowlisting for additional security
- Automatic retry with exponential backoff
Verifying Webhooks
Verify webhook authenticity using the signature header:
python
import hmac
import hashlib
def verify_webhook(payload, signature, secret):
expected = hmac.new(
secret.encode(),
payload.encode(),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(f"sha256={expected}", signature)Retry Logic
Failed webhook deliveries are automatically retried:
- Initial retry after 1 second
- Exponential backoff up to 1 hour
- Maximum of 10 retry attempts
- Webhook disabled after repeated failures
Ensure your webhook endpoint responds with 2xx status codes to confirm successful delivery.
Use Cases
- Trigger downstream workflows in your application
- Send notifications to Slack, Discord, or email
- Update databases with scraped data
- Generate reports and analytics
- Integrate with CI/CD pipelines
- Power real-time dashboards and monitoring