Webhooks

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:

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:

{
    "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:

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

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