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.

• 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 processing completes. The callback payload has the same shape as the status response.

Callback URLs must use HTTPS. TeamWeb AI validates the resolved IP address to prevent requests to private networks (RFC 1918, loopback, link-local addresses).

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