Documentation Index
Fetch the complete documentation index at: https://docs.cloudshipai.com/llms.txt
Use this file to discover all available pages before exploring further.
Event-Triggered Execution
Trigger agent execution from external systems via HTTP webhook. Perfect for integrating with CI/CD pipelines, alerting systems, or any automation that can make HTTP requests.
Endpoint
POST http://localhost:8587/execute
# Trigger by agent name
curl -X POST http://localhost:8587/execute \
-H "Content-Type: application/json" \
-d '{"agent_name": "incident_coordinator", "task": "Investigate the API timeout alert"}'
# Trigger by agent ID
curl -X POST http://localhost:8587/execute \
-H "Content-Type: application/json" \
-d '{"agent_id": 21, "task": "Check system health"}'
Request Parameters
| Field | Type | Required | Description |
|---|
agent_name | string | One of name/id | Agent name to execute |
agent_id | integer | One of name/id | Agent ID to execute |
task | string | Yes | Task/prompt for the agent |
variables | object | No | Variables for template rendering |
With Variables
curl -X POST http://localhost:8587/execute \
-H "Content-Type: application/json" \
-d '{
"agent_name": "cost_analyzer",
"task": "Analyze costs for project",
"variables": {"project_id": "prod-123", "region": "us-east-1"}
}'
Response
Success (202 Accepted)
{
"run_id": 120,
"agent_id": 21,
"agent_name": "incident_coordinator",
"status": "running",
"message": "Agent execution started"
}
Error (400/401/404)
{
"error": "agent not found",
"message": "No agent with name 'unknown_agent'"
}
Authentication
Local Mode (Default)
No authentication required when running locally.
Production
Set a static API key:
export STN_WEBHOOK_API_KEY="your-secret-key"
curl -X POST http://localhost:8587/execute \
-H "Authorization: Bearer your-secret-key" \
-H "Content-Type: application/json" \
-d '{"agent_name": "my-agent", "task": "Do something"}'
CloudShip OAuth
When CloudShip OAuth is enabled, webhook requests use the same OAuth flow as MCP clients.
Integration Examples
Auto-investigate when alerts fire:
curl -X POST https://your-station:8587/execute \
-H "Authorization: Bearer $STN_WEBHOOK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_name": "incident_coordinator",
"task": "PagerDuty alert: High CPU usage on payment-service"
}'
GitHub Actions
Trigger analysis on deployment:
# .github/workflows/deploy.yml
- name: Run deployment analyzer
run: |
curl -X POST ${{ secrets.STATION_URL }}/execute \
-H "Authorization: Bearer ${{ secrets.STATION_API_KEY }}" \
-H "Content-Type: application/json" \
-d '{
"agent_name": "deployment_analyzer",
"task": "Analyze deployment ${{ github.sha }}",
"variables": {
"commit": "${{ github.sha }}",
"branch": "${{ github.ref_name }}"
}
}'
Datadog Monitor
Trigger from Datadog webhook:
{
"agent_name": "metrics_investigator",
"task": "Investigate alert: {{alertTitle}} - {{alertScope}}",
"variables": {
"alert_id": "{{alertId}}",
"severity": "{{alertPriority}}"
}
}
Slack Slash Command
Create a Slack app that posts to your Station:
# Slack sends: /investigate high memory on api-gateway
curl -X POST https://your-station:8587/execute \
-H "Authorization: Bearer $API_KEY" \
-d '{
"agent_name": "incident_coordinator",
"task": "high memory on api-gateway"
}'
Prometheus Alertmanager
Configure alertmanager webhook:
# alertmanager.yml
receivers:
- name: 'station'
webhook_configs:
- url: 'https://your-station:8587/execute'
http_config:
bearer_token: 'your-api-key'
send_resolved: true
Configuration
Enable/Disable
# Enable webhook (default: true)
export STN_WEBHOOK_ENABLED=true
# Disable webhook
export STN_WEBHOOK_ENABLED=false
API Key
# Set static API key for authentication
export STN_WEBHOOK_API_KEY="your-secret-key"
In config.yaml
# config.yaml
webhook:
enabled: true
api_key: "{{ .STN_WEBHOOK_API_KEY }}"
Checking Run Status
After triggering, use the run_id to check status:
# Via API
curl http://localhost:8585/api/v1/runs/120
# Via CLI
stn runs inspect 120
# Via MCP tool
"Inspect run 120"
Async Execution
Webhook triggers are asynchronous - the response returns immediately with a run_id. The agent executes in the background.
To wait for completion, poll the run status:
# Poll until complete
while true; do
status=$(curl -s http://localhost:8585/api/v1/runs/120 | jq -r '.status')
if [ "$status" = "completed" ] || [ "$status" = "error" ]; then
break
fi
sleep 2
done
Security Considerations
- Always use API keys in production - Never expose unauthenticated webhooks
- Use HTTPS - Encrypt webhook traffic
- Validate sources - Consider IP allowlisting for known sources
- Rate limiting - Station doesn’t rate limit by default; use a reverse proxy
- Audit logs - All webhook executions are logged with source info
Troubleshooting
Connection Refused
Error: connection refused
- Station is running:
stn status
- Port 8587 is accessible
- Firewall allows inbound connections
401 Unauthorized
Check:
STN_WEBHOOK_API_KEY is set on Station- Request includes
Authorization: Bearer <key> header
- Key matches exactly
Agent Not Found
Check:
- Agent name is correct (case-sensitive)
- Agent exists:
stn agent list
- Agent is enabled
Run Fails
Check run details:
stn runs inspect <run_id>
- Agent prompt errors
- MCP tool failures
- Timeout exceeded
Comparison: Webhooks vs Notify
| Feature | Webhooks (this page) | Notify Tool |
|---|
| Direction | External → Station | Station → External |
| Purpose | Trigger agents | Send notifications |
| Endpoint | POST /execute | Configured webhook URL |
| Example | PagerDuty triggers investigation | Agent sends Slack alert |
Next Steps
