Webhooks & Hook Events

​

Webhooks — Outbound HTTP Notifications

​

Register a Webhook

curl -X POST https://www.hitheo.ai/api/v1/webhooks \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/theo",
    "event_types": ["completion.created", "job.completed"]
  }'

const webhook = await theo.createWebhook({
  url: "https://your-server.com/webhooks/theo",
  event_types: ["completion.created", "job.completed"],
});
// Save webhook.signing_secret — shown once only

​

Event Catalog

​

Verify Signatures

Theo-Webhook-Signature: v1=<hex>
Theo-Webhook-Timestamp: <unix_seconds>
Theo-Webhook-Id: <event_id>

​

Retry Behavior

• Automatic retries with exponential backoff on transient failures
• Per-attempt timeout enforced server-side
• 4xx errors are not retried (client errors)
• Webhooks are auto-disabled after a sustained run of failed deliveries
• Every attempt — successful or failed — is recorded in the delivery log

​

Manage Webhooks

• GET /api/v1/webhooks — List all webhooks
• PATCH /api/v1/webhooks/{id} — Update URL, event types, enable/disable
• DELETE /api/v1/webhooks/{id} — Remove
• POST /api/v1/webhooks/{id}/test — Send a test event
• GET /api/v1/webhooks/{id}/deliveries — View delivery log

​

Hook Events — Autonomous Skill Triggers

​

How Hooks Work

1. An event is published (via POST /api/v1/events or internal platform events)
2. The hook evaluator checks all enabled hooks for pattern matches
3. Matching hooks load the associated skill and execute it autonomously
4. Results are recorded in the execution log

​

Hook Presets

​

Install a Hook

# Using a preset
curl -X POST https://www.hitheo.ai/api/v1/hooks \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hook_preset_id": "share.accepted.welcome",
    "skill_slug": "email-drafter"
  }'

# Using a custom event pattern
curl -X POST https://www.hitheo.ai/api/v1/hooks \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_pattern": "order.*.completed",
    "skill_slug": "my-order-processor",
    "cooldown_minutes": 5
  }'

// Preset
await theo.createHook({
  hook_preset_id: "share.accepted.welcome",
  skill_slug: "email-drafter",
});

// Custom pattern
await theo.createHook({
  event_pattern: "order.*.completed",
  skill_slug: "my-order-processor",
  cooldown_minutes: 5,
});

​

Custom Event Patterns

• Exact match: share.accepted matches only share.accepted
• Glob wildcard: order.*.completed matches order.purchase.completed, order.return.completed
• Prefix match: share matches share.accepted, share.declined, etc.
• Catch-all: * matches everything

​

Publishing Events

await theo.publishEvent({
  orgId: "your-org-id",
  eventType: "order.purchase.completed",
  payload: { orderId: "ORD-123", total: 299.99 },
});

​

Guard Rails

• Pre-flight credit check before each run
• Separate daily cap for autonomous actions
• Per-run caps on tool invocations and total spend
• Credit checkpoint between steps
• Hooks auto-pause after repeated failures
• Configurable cooldown between firings to prevent runaway execution

​

Manage Hooks

• GET /api/v1/hooks — List hooks (includes available presets)
• PATCH /api/v1/hooks/{id} — Update config, enable/disable
• DELETE /api/v1/hooks/{id} — Remove
• GET /api/v1/hooks/{id} — View execution history