Skip to main content

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.

​
Overview

The notify tool allows agents to send outbound notifications via webhooks. Use it to alert users about task completion, errors, or important updates.
Looking for inbound triggers? To trigger agents FROM external systems (like PagerDuty or GitHub Actions), see Event-Triggered Execution.
The notify tool is a native Station capability - no MCP server required. Configure it once, and any agent can send notifications.

​
Configuration

Station can send notifications to any HTTP POST endpoint - ntfy.sh, Slack, Discord, custom webhooks, or any service that accepts POST requests. Add the notify configuration to your config.yaml: 
notify:
  webhook_url: https://ntfy.sh/your-topic   # Any POST endpoint
  api_key: your-api-key                      # Optional Bearer token
  timeout_seconds: 10                        # Default: 10
  format: ntfy                               # ntfy, json, or auto

​
Configuration Options

FieldTypeDefaultDescription
webhook_urlstring-Any HTTP POST endpoint (required)
api_keystring-Bearer token for authentication (optional)
timeout_secondsint10Request timeout
formatstringautoWebhook format: ntfy, json, or auto

​
Formats

FormatWhen to UseDescription
ntfyntfy.sh or self-hosted ntfySends message in body, metadata in HTTP headers (Title, Priority, Tags)
jsonSlack, Discord, custom APIsSends full JSON payload with all fields
autoDefaultAuto-detects ntfy URLs (ntfy.sh or /ntfy), falls back to JSON for others
Use format: json to send to any webhook that accepts POST requests with JSON body.

​
Environment Variables

For containerized deployments, use environment variables: 
STN_NOTIFY_WEBHOOK_URL=https://your-webhook.com/endpoint
STN_NOTIFY_API_KEY=your-token
STN_NOTIFY_TIMEOUT=10
STN_NOTIFY_FORMAT=ntfy

​
Enabling for Agents

​
Via Frontmatter (.prompt file)

Add notify: true to your agent’s frontmatter: 
---
model: anthropic/claude-sonnet-4-20250514
notify: true
---
You are a monitoring agent. When you detect issues, use the notify tool to alert the user.

Use the notify tool with:
- message: Description of what happened
- title: Brief subject line
- priority: "high" for urgent issues
- tags: Use "warning" for alerts, "white_check_mark" for success

​
Via MCP Tools

Enable notify when creating an agent: 
"Create a monitoring agent with notify enabled"
The create_agent tool accepts a notify parameter: 
{
  "name": "alert-bot",
  "description": "Sends alerts when issues detected",
  "prompt": "You monitor systems and send notifications...",
  "environment_id": "1",
  "notify": true
}
Enable/disable on existing agents with update_agent: 
"Enable notifications for the incident-coordinator agent"

{
  "agent_id": "21",
  "notify": true
}
The notify tool only appears for agents with notify: true AND a configured notify.webhook_url in Station config.

​
Tool Parameters

When called, the notify tool accepts:
ParameterTypeRequiredDescription
messagestringYesNotification content
titlestringNoSubject line
prioritystringNomin, low, default, high, urgent
tagsarrayNoEmoji tags (e.g., ["warning", "robot"])

​
Webhook Formats

​
ntfy Format

When format: ntfy, notifications are sent with headers: 
POST /your-topic HTTP/1.1
Host: ntfy.sh
Authorization: Bearer your-api-key
Title: Alert Title
Priority: high
Tags: warning,robot

Your notification message here

​
JSON Format

When format: json, notifications are sent as JSON: 
{
  "message": "Your notification message",
  "title": "Alert Title",
  "priority": "high",
  "tags": ["warning", "robot"],
  "timestamp": "2026-01-02T19:30:00Z"
}

​
Examples

​
ntfy.sh (Official)

notify:
  webhook_url: https://ntfy.sh/my-alerts
  api_key: tk_your_token_here
  format: ntfy

​
Self-Hosted ntfy

notify:
  webhook_url: https://ntfy.mycompany.com/alerts
  api_key: your-token
  format: ntfy

​
Generic Webhook (Slack, Discord, Custom)

notify:
  webhook_url: https://hooks.slack.com/services/xxx/yyy/zzz
  format: json

​
Auto-Detection

notify:
  webhook_url: https://ntfy.sh/topic
  format: auto  # Will use ntfy format

​
Agent Examples

​
Alert Agent

---
model: anthropic/claude-sonnet-4-20250514
notify: true
---
You are an alert agent. When asked to send alerts, use the notify tool immediately.

For urgent issues, use priority "high" and tags ["warning"].
For success notifications, use tags ["white_check_mark"].

​
Monitoring Agent

---
model: gpt-4o-mini
notify: true
tools:
  - "__check_system_health"
---
You monitor systems and send notifications when issues are detected.

After each health check:
1. If issues found: notify with priority "high" and tag "warning"
2. If all healthy: notify with tag "white_check_mark"

​
Tracing

Notify tool calls are traced with OpenTelemetry:
AttributeDescription
notify.successWhether notification was sent
notify.message_idID returned by webhook (if available)
notify.message_lengthLength of message
notify.priorityPriority level used

​
Troubleshooting

​
Notification Not Sent

  1. Check webhook_url is accessible
  2. Verify api_key if endpoint requires authentication
  3. Check Station logs for error messages

​
Wrong Format

If self-hosted ntfy isn’t detected, explicitly set format: ntfy: 
notify:
  webhook_url: https://notifications.internal/alerts
  format: ntfy  # Force ntfy format

​
Testing

Test your webhook directly: 
curl -X POST https://ntfy.sh/your-topic \
  -H "Authorization: Bearer your-token" \
  -H "Title: Test" \
  -d "Test message"

​
Notifications vs Webhooks

FeatureNotify (this page)Webhooks
DirectionStation → ExternalExternal → Station
PurposeSend alerts/notificationsTrigger agent execution
Use caseAgent alerts userPagerDuty triggers agent
Configurationnotify: in config.yamlSTN_WEBHOOK_API_KEY
See Event-Triggered Execution for inbound triggers.

​
Next Steps