> ## 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.

# Outbound Notifications

> Send webhook notifications from your agents to external systems

## Overview

The notify tool allows agents to send **outbound** notifications via webhooks. Use it to alert users about task completion, errors, or important updates.

<Note>
  **Looking for inbound triggers?** To trigger agents FROM external systems (like PagerDuty or GitHub Actions), see [Event-Triggered Execution](/station/webhooks).
</Note>

<Note>
  The notify tool is a native Station capability - no MCP server required. Configure it once, and any agent can send notifications.
</Note>

## 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`:

```yaml theme={null}
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 |

<Tip>
  Use `format: json` to send to **any webhook** that accepts POST requests with JSON body.
</Tip>

## Environment Variables

For containerized deployments, use environment variables:

```bash theme={null}
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:

```yaml theme={null}
---
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:

```json theme={null}
{
  "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"
```

```json theme={null}
{
  "agent_id": "21",
  "notify": true
}
```

<Note>
  The notify tool only appears for agents with `notify: true` AND a configured `notify.webhook_url` in Station config.
</Note>

## 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:

```http theme={null}
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:

```json theme={null}
{
  "message": "Your notification message",
  "title": "Alert Title",
  "priority": "high",
  "tags": ["warning", "robot"],
  "timestamp": "2026-01-02T19:30:00Z"
}
```

## Examples

### ntfy.sh (Official)

```yaml theme={null}
notify:
  webhook_url: https://ntfy.sh/my-alerts
  api_key: tk_your_token_here
  format: ntfy
```

### Self-Hosted ntfy

```yaml theme={null}
notify:
  webhook_url: https://ntfy.mycompany.com/alerts
  api_key: your-token
  format: ntfy
```

### Generic Webhook (Slack, Discord, Custom)

```yaml theme={null}
notify:
  webhook_url: https://hooks.slack.com/services/xxx/yyy/zzz
  format: json
```

### Auto-Detection

```yaml theme={null}
notify:
  webhook_url: https://ntfy.sh/topic
  format: auto  # Will use ntfy format
```

## Agent Examples

### Alert Agent

```yaml theme={null}
---
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

```yaml theme={null}
---
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

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`:

```yaml theme={null}
notify:
  webhook_url: https://notifications.internal/alerts
  format: ntfy  # Force ntfy format
```

### Testing

Test your webhook directly:

```bash theme={null}
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](/station/webhooks) for inbound triggers.

## Next Steps

* [Webhooks](/station/webhooks) - Trigger agents from external systems
* [Scheduling](/station/scheduling) - Cron-based execution
* [Observability](/station/observability) - Monitor notifications