Outbound Notifications

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`

Formats

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

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:

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"]`)

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:

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

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

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`

See Event-Triggered Execution for inbound triggers.

Next Steps

Webhooks - Trigger agents from external systems
Scheduling - Cron-based execution
Observability - Monitor notifications

Get Started

Station CLI

Building Agents

Station Lattice

Deployment

Advanced

Overview

Configuration

Configuration Options

Formats

Environment Variables

Enabling for Agents

Via Frontmatter (.prompt file)

Via MCP Tools

Tool Parameters

Webhook Formats

ntfy Format

JSON Format

Examples

ntfy.sh (Official)

Self-Hosted ntfy

Generic Webhook (Slack, Discord, Custom)

Auto-Detection

Agent Examples

Alert Agent

Monitoring Agent

Tracing

Troubleshooting

Notification Not Sent

Wrong Format

Testing

Notifications vs Webhooks

Next Steps

​Overview

​Configuration

​Configuration Options

​Formats

​Environment Variables

​Enabling for Agents

​Via Frontmatter (.prompt file)

​Via MCP Tools

​Tool Parameters

​Webhook Formats

​ntfy Format

​JSON Format

​Examples

​ntfy.sh (Official)

​Self-Hosted ntfy

​Generic Webhook (Slack, Discord, Custom)

​Auto-Detection

​Agent Examples

​Alert Agent

​Monitoring Agent

​Tracing

​Troubleshooting

​Notification Not Sent

​Wrong Format

​Testing

​Notifications vs Webhooks

​Next Steps

Overview

Configuration

Configuration Options

Formats

Environment Variables

Enabling for Agents

Via Frontmatter (.prompt file)

Via MCP Tools

Tool Parameters

Webhook Formats

ntfy Format

JSON Format

Examples

ntfy.sh (Official)

Self-Hosted ntfy

Generic Webhook (Slack, Discord, Custom)

Auto-Detection

Agent Examples

Alert Agent

Monitoring Agent

Tracing

Troubleshooting

Notification Not Sent

Wrong Format

Testing

Notifications vs Webhooks

Next Steps