Documentation

Triggers and Webhooks

View as Markdown

Agents support several trigger types for operational AI. Inbound triggers validate incoming values, map them to Agent variables, and create a run.

Common trigger sources include:

  • Webhooks from external systems
  • Upload triggers from Site file activity
  • Sub-agent triggers from another Agent
  • Schedules for recurring execution

Outgoing webhooks are a separate step type used to send Agent results to external systems when policy allows it.

Incoming Webhook Triggers

Incoming webhooks let external systems start an Agent run by sending an authenticated HTTP request to a Clear Ideas webhook URL.

Typical setup:

  1. Enable webhook triggers on the Agent.
  2. Configure trigger variable mappings.
  3. Create a webhook access key with the receive_events scope.
  4. Copy the generated webhook URL.
  5. Send authenticated POST requests with JSON payloads.
  6. Review the created Agent run.

Authentication

Webhook requests require authentication.

Supported approaches include:

  • Webhook access key with the receive_events scope
  • OAuth2 bearer token from an authenticated Clear Ideas session

Use access keys for server-to-server integrations. Create and manage access keys in Settings > Access Keys.

See Access Keys.

Payload Mapping

Trigger variable mappings define how request payload fields become Agent variables.

For each mapping, configure:

  • payload key
  • target variable name
  • data type
  • required or optional status

Payload keys can use dot notation for nested JSON fields.

Strict Payload Validation

Webhook triggers can reject unmapped top-level payload keys. Use strict validation when the webhook payload is treated as an API contract and extra fields should fail the request.

Without strict validation, required mapped keys are still enforced, but extra unmapped fields are ignored.

Default Sites

You can configure default Sites for webhook-triggered runs. The run uses those Sites for context unless the trigger payload supplies a different allowed scope.

Default Sites are useful for customer-specific automations, recurring reports, and integrations that should always run against the same approved content set.

Upload Triggers

Upload triggers start work when files are added to a Site or folder. Upload-triggered applicability, including Site and folder rules, is configured in Site Settings > Extraction Workflows.

Use upload triggers for metadata extraction, document classification, intake review, recurring filing checks, or automatic summary generation.

See Extraction Workflows.

Sub-Agent Triggers

Sub-agent triggers let one Agent invoke another Agent as part of a larger process. The parent Agent maps values into the child Agent's required and optional trigger variables, waits for the child run, and continues with the child output.

Use sub-agent execution to split large processes into reusable components, such as extraction, review, quality checks, and report generation.

Outgoing Webhook Steps

Outgoing webhook steps send Agent results to external systems when allowed by policy. Use them for integration patterns such as notifying a CRM, posting a summary to an internal system, or sending a generated result to an approved endpoint.

Review controlled tools and egress settings before enabling outgoing webhooks for sensitive Agents.

See Controlled Tools and Egress.