Skip to main content
Theo supports two complementary event systems for the E.V.I. canvas Input node’s Webhook Event and Hook Event trigger types.

​
Webhooks — Outbound HTTP Notifications

Webhooks deliver events to your HTTP endpoints. When something happens in Theo (completion, job finish, skill install, etc.), a signed POST is sent to every matching endpoint.

​
Register a Webhook

curl -X POST https://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"]
  }'
The response includes a signing_secret — save it securely. It’s shown once and used to verify payloads.

​
Event Catalog

EventDescription
completion.createdA completion was generated
job.completed / job.failedBackground job finished
workflow.completed / workflow.failedWorkflow run finished
skill.installed / skill.uninstalledSkill install/uninstall
skill.submitted / skill.approved / skill.rejectedSkill review
connector.created / connector.status_changedConnector events
credits.lowCredit balance low
key.created / key.revokedAPI key events
Use "*" as an event type to receive all events.

​
Verify Signatures

Every delivery includes HMAC-SHA256 signatures: 
Theo-Webhook-Signature: v1=<hex>
Theo-Webhook-Timestamp: <unix_seconds>
Theo-Webhook-Id: <event_id>
Verify by computing HMAC-SHA256(signing_secret, timestamp + "." + raw_body) and comparing. Reject if the timestamp drifts more than 5 minutes.

​
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

Hooks are internal event triggers that automatically execute skills when events occur — no HTTP endpoint needed. The skill runs headless via the autonomous executor with credit guards.

​
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

PresetEvent PatternDefault SkillDescription
share.accepted.welcomeshare.acceptedemail-drafterWelcome on share accept
task.overdue.summarytask.overduetodo-managerSummarize overdue tasks
project.created.suggestionsproject.createddocument-analyzerSuggest project next steps
team.member_joined.onboardingteam.member_joinedemail-drafterOnboarding guidance
document.analyzed.followupdocument.analyzeddocument-analyzerFollow-up action items

​
Install a Hook

# Using a preset
curl -X POST https://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://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
  }'

​
Custom Event Patterns

Patterns support:
  • 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

Use POST /api/v1/events to publish domain events that trigger hooks and webhooks: 
await theo.publishEvent({
  orgId: "your-org-id",
  eventType: "order.purchase.completed",
  payload: { orderId: "ORD-123", total: 299.99 },
});

​
Guard Rails

Autonomous execution runs under strict safety limits:
  • 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