Web Trigger

The Web Trigger channel allows external services to trigger assistant conversations via HTTP POST requests. This enables integrations with automation platforms like Zapier, Make, and n8n without building native connectors.

When configured:

• External services authenticate with an API key and send a message to trigger a conversation
• The assistant processes the message asynchronously in the background
• Results can be retrieved by polling a status endpoint
• Optionally, results can be delivered to a callback URL when processing completes

Configuration

Enable the Web Trigger channel on your assistant’s Channels tab. The only configuration option is:

API Keys

API keys authenticate requests to the web trigger endpoint. Manage keys from Admin > API Keys in the sidebar, under the Assistant Keys tab.

• Keys are 64-character hex tokens generated by TeamWeb AI
• The full key is shown only once at creation — copy and store it securely
• Each key is scoped to a single assistant and identified by a name and an 8-character prefix
• Keys can be revoked at any time (integrations using a revoked key will immediately stop working)
• Multiple keys can be created per assistant for key rotation

Trigger Endpoint

POST /api/v1/assistants/<assistant_id>/web-trigger

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request body:

{
  "message": "Summarise the latest sales report",
  "subject": "Weekly Report",
  "context": {
    "region": "APAC",
    "customer": "Acme Corp"
  },
  "task_definition_id": 5,
  "callback_url": "https://hooks.zapier.com/abc123",
  "metadata": {
    "source": "zapier",
    "zap_id": "456"
  }
}

Response (202 Accepted):

{
  "trigger_id": 42,
  "status": "accepted",
  "status_url": "https://yourdomain.com/api/v1/web-triggers/42/status"
}

Polling for Results

GET /api/v1/web-triggers/<trigger_id>/status

The trigger_id is returned in the trigger response above. Include the same Authorization: Bearer header. The API key must belong to the same assistant.

Response:

{
  "trigger_id": 42,
  "status": "completed",
  "result": "Here is the summary of the latest sales report...",
  "created_at": "2025-01-15T10:00:00",
  "completed_at": "2025-01-15T10:01:23"
}

Callback Delivery

When callback_url is provided and callbacks are enabled, TeamWeb AI will POST the result to the URL when the agent run reaches any terminal state — completed, failed, cancelled, or timed_out.

Payload:

{
  "run_key": "f7d2c1a8-3b4e-4f5a-9c0d-1e2f3a4b5c6d",
  "status": "completed",
  "status_detail": null,
  "result_text": "Here is the summary of the latest sales report...",
  "error_message": null,
  "conversation_id": 42,
  "events_url": "https://yourdomain.com/conversations/42/agent-events?run_id=17",
  "completed_at": "2026-04-15T10:01:23+00:00"
}

Callback URLs must use HTTPS. TeamWeb AI validates the resolved IP address to prevent requests to private networks (RFC 1918, loopback, link-local addresses). Callbacks are delivered exactly once per terminal transition — failures are logged but not auto-retried, so the receiver must be idempotent on run_key.

Live Event Stream

For long-running triggers you can subscribe to a live Server-Sent Events feed instead of polling. The events_url returned in the callback (or constructed from the trigger response as /conversations/<trigger_id>/agent-events?run_id=<run_id>) emits a data: {...} line for each lifecycle event:

data: {"event_type": "run_started", "sequence": 2, ...}

data: {"event_type": "tool_started", "payload": {"tool": "search_knowledge"}, ...}

data: {"event_type": "run_completed", "sequence": 14, ...}

: heartbeat

Heartbeat frames (: heartbeat) fire every 15 seconds so the connection stays alive through proxies. Each event also carries an id: <int> SSE field so browsers reconnect automatically via the Last-Event-ID header — no manual cursor tracking needed. For programmatic clients, pass ?after_event_id=N (conversation streams) or ?after_sequence=N (run-scoped streams via ?run_id=X) to skip events you’ve already seen.

The endpoint requires the same authenticated session as the rest of the admin UI; it is not yet exposed for unauthenticated API key access. For Bearer-token integrations, prefer the polling endpoint or the callback delivery above.

Task Definitions

When task_definition_id is provided, the trigger executes a pre-configured task definition rather than an ad-hoc conversation. The task definition’s own instructions, output type, and tool allowlist are used. The message field provides additional context for the task execution.

Task definitions can be created and managed under Tasks in the sidebar.

Example: cURL

# Trigger a conversation
curl -X POST https://yourdomain.com/api/v1/assistants/1/web-trigger \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the top 3 trending topics this week?",
    "context": {"industry": "technology"}
  }'

# Poll for results (use the trigger_id from the response above)
curl https://yourdomain.com/api/v1/web-triggers/42/status \
  -H "Authorization: Bearer your_api_key_here"

Security

• API keys are stored as SHA-256 hashes — the plaintext key is never stored
• Each key is scoped to a single assistant
• Callback URL delivery includes SSRF protection (blocks private/internal IP ranges)
• The endpoint is CSRF-exempt (stateless Bearer token auth)
• Keys can be revoked instantly if compromised