Triggers

Schedule recurring automated actions with cron-based triggers that dispatch workspace actions on a defined cadence.

Triggers bind cron schedules to actions. When a trigger fires, the referenced action is dispatched and executed immediately. Each trigger is workspace-scoped and tracks its own execution history.

Use case: schedule a nightly patient outreach action, a weekly report generation, or periodic data quality checks. Any action that should run on a recurring basis without manual intervention.

Endpoints

All trigger endpoints are scoped to a workspace: /v1/{workspace_id}/triggers.

Create Trigger

POST /v1/{workspace_id}/triggers

Field	Type	Required	Description
name	string	Yes	Trigger name
description	string	No	Human-readable description
event_type	string	Yes	Event type identifier
event_filter	object	No	Optional filter conditions on the event type
action_id	string (UUID)	Yes	ID of the action to dispatch when the trigger fires
input_template	object	No	Parameterized input passed to the action on each execution
schedule	string	No	Cron expression (e.g., 0 9 * * MON-FRI for weekday mornings at 9 AM)
timezone	string	No	IANA timezone for schedule evaluation (default: UTC)

Response: 201 Created with the full trigger object including computed next_fire_at.

List Triggers

GET /v1/{workspace_id}/triggers

Parameter	Type	Description
is_active	boolean	Filter by active/paused state
limit	integer	Items per page (default 10, max 20)
continuation_token	integer	Pagination offset

Get Trigger

GET /v1/{workspace_id}/triggers/{trigger_id}

Update Trigger

PUT /v1/{workspace_id}/triggers/{trigger_id}

Accepts any subset of the create fields. The schedule's next_fire_at is recomputed when the schedule or timezone fields change.

Delete Trigger

DELETE /v1/{workspace_id}/triggers/{trigger_id}

Returns 204 No Content.

Pause Trigger

POST /v1/{workspace_id}/triggers/{trigger_id}/pause

Pauses the trigger's schedule. The trigger remains in the workspace but will not fire until resumed. Returns the updated trigger object with is_active: false.

Resume Trigger

POST /v1/{workspace_id}/triggers/{trigger_id}/resume

Resumes a paused trigger. The next_fire_at is recomputed from the current time. Returns the updated trigger object with is_active: true.

Fire Trigger (Manual)

POST /v1/{workspace_id}/triggers/{trigger_id}/fire

Manually dispatches the trigger's action immediately, regardless of the cron schedule or active state. Useful for testing trigger configurations before enabling the schedule.

Accepts an optional JSON body with an input field. Values from the override are merged into the trigger's stored input_template at fire time, so callers can supply dynamic values without modifying the trigger configuration. This is the mechanism webhook destinations use to pass extracted payload fields through to the action.

Field	Type	Description
input	object	Optional key-value pairs merged into the trigger's input_template at fire time. Override values take precedence over template values.

Response:

Field	Type	Description
fired_event_id	string (UUID)	ID of the event created by this fire
trigger_id	string (UUID)	The trigger that was fired
status	string	Always "fired"

Execution History

GET /v1/{workspace_id}/triggers/{trigger_id}/runs

Returns the trigger's execution history as a list of events, ordered by most recent first.

Field	Type	Description
event_id	string (UUID)	Event ID for this execution
event_type	string	Event type that was dispatched
data	object	Event data payload
effective_at	string (datetime)	When the event took effect
created_at	string (datetime)	When the event was created

Trigger Object

Field	Type	Description
id	string (UUID)	Trigger ID
workspace_id	string (UUID)	Owning workspace
name	string	Trigger name
description	string or null	Description
event_type	string	Event type identifier
event_filter	object or null	Filter conditions
action_id	string (UUID)	Action to dispatch
input_template	object	Input passed to the action
schedule	string or null	Cron expression
timezone	string	IANA timezone (default UTC)
next_fire_at	string (datetime) or null	Next scheduled fire time
is_active	boolean	Whether the trigger is active
created_by	string or null	API key entity that created the trigger
created_at	string (datetime)	Creation timestamp
updated_at	string (datetime)	Last update timestamp

Webhook-Based Activation

Triggers can be fired by inbound webhooks from external systems (CRMs, scheduling platforms, workflow automation tools). A webhook destination links an external endpoint to a trigger. When the external system POSTs to the destination URL, the platform verifies the signature, validates the event, and fires the linked trigger.

Webhook Destination Fields

Field	Type	Description
accepted_event_types	array of strings	Whitelist of event types this destination accepts. When set, the platform extracts the event type from the signed payload body and rejects events that don't match (422 response). Maximum 50 entries.
retry_attempts	integer	Number of retry attempts for transient failures. Retries use exponential backoff and only apply to connection-level errors (timeouts, network failures), not application errors. Range: 1-5. Default: 3.
field_mapping	object or null	Maps incoming payload fields to the trigger's input template fields before firing.
trigger_id	string (UUID)	The trigger to fire when a valid webhook is received.

Event Type Extraction

The event type is extracted from the signed request body by checking these payload fields in priority order: type, event_type, event, action. The first non-empty string value found is used as the event type. Unsigned request headers are not used for event type extraction. This prevents event type spoofing through replay attacks with modified headers.

Retry Behavior

The platform retries webhook delivery on transient connection errors (timeouts, network failures) with exponential backoff starting at 0.5 seconds. Only connection-level errors are retried: application errors that may have already persisted data are not retried, to avoid duplicate events.

Webhook → Outbound Call

The most common webhook integration pattern is triggering an outbound voice call when an external system sends a lead or event notification. Here is how to wire it up end-to-end.

1. Create a skill with action_type: "schedule_outbound_call"

forge platform skill create \
  --name "Schedule Outbound Intake Call" \
  --config '{
    "action_type": "schedule_outbound_call",
    "system_prompt": "...",
    "model": "claude-sonnet-4-6"
  }'

The action_type field tells the platform to use the deterministic outbound path — no LLM reasoning loop, just direct task creation. This is faster, cheaper, and produces consistent results.

2. Create a trigger bound to the skill

forge platform trigger create \
  --name "outbound-intake-call" \
  --action-id "<skill_id>" \
  --input-template '{"phone_to": ""}'

The input_template defines the shape of the input the action expects. At fire time, values from the webhook payload are merged into this template via field mapping.

3. Create a webhook destination

forge platform webhook-destination create \
  --name "crm-intake" \
  --trigger-id "<trigger_id>" \
  --field-mapping '{"phone_to": "contact.phone"}'

The field_mapping extracts fields from the incoming webhook payload using dot notation. In this example, contact.phone from the CRM payload is mapped to phone_to in the trigger input.

4. Configure the external system

Point the external system's webhook URL to:

POST https://api.platform.amigo.ai/v1/{workspace_id}/hooks/{destination_id}

Sign requests with HMAC-SHA256 using the destination's signing secret (returned at creation time). Include the signature in the x-amigo-request-signature header.

How the dispatch chain works

When the external system POSTs to the webhook URL:

External System (CRM, Zapier, GHL)
  │
  ▼  POST /v1/{workspace_id}/hooks/{destination_id}
  │  HMAC-SHA256 verification
  │  Idempotency dedup (600s window)
  │  Event type whitelist check
  │  Field mapping applied
  │
  ▼  Trigger fires
  │  Creates outbound_task entity with status=scheduled
  │  Emits outbound.scheduled event to the world model
  │
  ▼  Dispatch loop (runs every 30s)
  │  Queries due tasks: status=scheduled, next_attempt_at <= now
  │  Checks business hours window
  │  Acquires distributed lock (prevents double-dispatch)
  │
  ▼  Voice call placed
  │  Agent loads patient context automatically
  │  Call outcome recorded as world model event
  │
  ▼  Retry on failure
     If attempts remain: reschedules with backoff
     If exhausted: marks task as failed

The webhook returns 200 OK with a fired_event_id immediately — call dispatch happens asynchronously. Expect 2–3 minutes between webhook receipt and call placement (event processing + entity sync + dispatch loop interval).

Input fields for outbound actions

When action_type is schedule_outbound_call, the merged input (template + webhook field mapping) accepts:

Field	Type	Required	Description
phone_to	string (E.164)	Yes	Destination phone number
reason	string	No	Why the call is being made (default: outbound_intake)
goal	string	No	What the agent should accomplish
priority	integer (1-10)	No	Dispatch priority, higher = first (default: 8)
max_attempts	integer (1-10)	No	Maximum call attempts (default: 3)
retry_backoff_minutes	integer	No	Minutes between retries (default: 30)
window	object	No	Business hours constraint (default: 09:00-18:00 America/New_York)
service_id	string (UUID)	No	Specific agent service to handle the call
patient_entity_id	string (UUID)	No	Link to existing patient entity for context loading
phone_from	string (E.164)	No	Caller ID override

Tracing a webhook through the system

Every webhook fire creates a chain of events you can trace:

1. trigger.fired — The trigger was activated (includes triggered_by: "webhook:{destination_id}")

2. outbound.scheduled — The outbound task entity was created with all scheduling parameters

3. trigger.completed — The action finished (includes duration_ms, events_written)

4. outbound.dispatched — The call was placed (includes call_sid)

5. outbound.completed or outbound.failed — Final outcome

Query these via the trigger's execution history endpoint or through the analytics layer.

Provenance

Events produced by trigger executions carry an AUTOMATION source tag, distinguishing them from conversation-driven or manual events in the world model. Execution history is tracked through event chains, with each fire creating an event linked to the trigger entity.

CLI

Triggers can be managed through Agent Forge: forge platform trigger create|list|get|update|delete|pause|resume|fire|runs. See the Agent Forge reference for details.