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
| Field | Type | Default | Description |
|---|
webhook_url | string | - | Any HTTP POST endpoint (required) |
api_key | string | - | Bearer token for authentication (optional) |
timeout_seconds | int | 10 | Request timeout |
format | string | auto | Webhook format: ntfy, json, or auto |
| Format | When to Use | Description |
|---|
ntfy | ntfy.sh or self-hosted ntfy | Sends message in body, metadata in HTTP headers (Title, Priority, Tags) |
json | Slack, Discord, custom APIs | Sends full JSON payload with all fields |
auto | Default | Auto-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
"Create a monitoring agent with notify enabled"
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
}
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.
| Parameter | Type | Required | Description |
|---|
message | string | Yes | Notification content |
title | string | No | Subject line |
priority | string | No | min, low, default, high, urgent |
tags | array | No | Emoji tags (e.g., ["warning", "robot"]) |
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
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:
| Attribute | Description |
|---|
notify.success | Whether notification was sent |
notify.message_id | ID returned by webhook (if available) |
notify.message_length | Length of message |
notify.priority | Priority level used |
Troubleshooting
Notification Not Sent
- Check
webhook_url is accessible
- Verify
api_key if endpoint requires authentication
- Check Station logs for error messages
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
| Feature | Notify (this page) | Webhooks |
|---|
| Direction | Station → External | External → Station |
| Purpose | Send alerts/notifications | Trigger agent execution |
| Use case | Agent alerts user | PagerDuty triggers agent |
| Configuration | notify: in config.yaml | STN_WEBHOOK_API_KEY |
Next Steps
