hooks field in their manifest (local plugins) or configuration (webhook plugins). Events follow the <entity>.<action> naming convention.
Event envelope
Every event includes these standard fields:Task events
task.created
Fires when a new task is inserted into the tasks table.
Emitted by: SQL trigger on tasks INSERT
Payload: Full task row as JSON — includes title, status, priority, assignee_agent_id, stream_id, due_date, and all other task fields.
task.completed
Fires when a task’s status changes to done.
Emitted by: SQL trigger on tasks.status UPDATE (only when new status = done and old status != done)
Payload: Task row with both old and new values. Key fields: title, assignee_agent_id, status (= done).
task.assigned
Fires when a task’s assignee_agent_id changes.
Emitted by: SQL trigger on tasks.assignee_agent_id UPDATE (only when the value actually changes)
Payload: Task row with old and new values. Key fields: old assignee_agent_id, new assignee_agent_id, title.
Agent events
agent.provisioned
Fires after a new agent is successfully provisioned on the gateway.
Emitted by: command_runner.py after a successful provision command (exit code 0)
Payload:
agent.deprovisioned
Fires after an agent is successfully removed from the gateway.
Emitted by: command_runner.py after a successful remove command
Payload:
agent.status_changed
Fires when an agent’s status changes (e.g. provisioning → ready, ready → paused).
Emitted by: SQL trigger on agents.status UPDATE
Payload: Agent row with old and new values. Key fields: old status, new status, slug, name.
Knowledge events
knowledge.created
Fires when a new knowledge item is inserted.
Emitted by: SQL trigger on knowledge_items INSERT
Payload: Full knowledge item row. Key fields: title, kind (page/skill/file/source), scope (workspace/agent).
knowledge.processed
Fires after text extraction completes for a file-type knowledge item.
Emitted by: file_processor.py after successful text extraction
Payload:
knowledge.embedded
Fires after embedding generation completes for a knowledge item.
Emitted by: embedder.py after successful embedding
Payload:
Inbox events
inbox.created
Fires when a new inbox item is queued for an agent.
Emitted by: SQL trigger on agent_inbox_items INSERT
Payload: Full inbox item row. Key fields: agent_id, event_type, task_id, summary.
inbox.completed
Fires when an inbox item’s status changes to done.
Emitted by: SQL trigger on agent_inbox_items.status UPDATE (only when new status = done)
Payload: Inbox item row with old and new values. Key fields: agent_id, event_type.
Routine events
routine.triggered
Fires when a routine creates an inbox item (either from a schedule or an event trigger).
Emitted by: SQL trigger on agent_inbox_items INSERT (only when event_type is routine_schedule or routine_event)
Payload: Inbox item row. Key fields: routine_id (from metadata), agent_id, event_type.
Communication events
comment.created
Fires when a comment is posted on any entity (task, contact, etc.).
Emitted by: SQL trigger on comments INSERT
Payload: Full comment row. Key fields: entity_type, entity_id, author_agent_id, body, mentioned_agent_ids.
Security events
secret.changed
Fires when a secret is added, updated, or removed. The secret value is never included in the payload — only metadata.
Emitted by: SQL trigger on secrets INSERT/UPDATE/DELETE
Payload: Secret metadata with sensitive fields stripped. Key fields: key, category, action (insert/update/delete).