Orbitr Documentation

Overview

Webhooks let you receive HTTP callbacks when events occur in Orbitr. Instead of polling the API for changes, Orbitr sends a POST request to your URL when something happens.

Events

Event	Description
`task.created`	A new task was created by an agent
`task.completed`	A task was successfully executed
`task.failed`	A task execution failed
`task.awaiting_approval`	A task is ready for your review
`audit.completed`	A site audit finished
`keyword.ranking_change`	A significant keyword ranking change detected

Webhook Payload

All webhook payloads follow the same structure:

{
  "event": "task.completed",
  "timestamp": "2026-02-25T14:30:00Z",
  "data": {
    "id": "task-uuid",
    "title": "Optimize meta description for /products",
    "status": "completed",
    "site_id": "site-uuid"
  }
}

Setup

Configure webhooks from Settings in the Orbitr dashboard:

Navigate to Settings
Find the Webhooks section
Click Add Webhook
Enter your endpoint URL
Select which events to subscribe to
Save

Security

Webhook requests include a signature header for verification:

X-Orbitr-Signature: sha256=abc123...

Verify this signature against your webhook secret to confirm the request came from Orbitr.

Retry Policy

If your endpoint returns a non-2xx status code, Orbitr retries the delivery:

1st retry: 1 minute after initial attempt
2nd retry: 5 minutes after
3rd retry: 30 minutes after
Final retry: 2 hours after

After 4 failed attempts, the webhook delivery is marked as failed. You can view failed deliveries in the webhook settings.

Best Practices

Respond quickly — Return a 200 status code within 5 seconds. Process the webhook payload asynchronously.
Handle duplicates — Use the event id to deduplicate in case of retries.
Verify signatures — Always verify the webhook signature before processing.

Webhooks