Alert Channels API

Alert channels define how and where you receive notifications when monitors go down or recover. PixoMonitor supports multiple notification methods.

All alert channel endpoints require authentication. Include the Authorization: Bearer {token} header with all requests.

Supported Channel Types

Type	Description	Required Config
`EMAIL`	Email notifications	`email` address
`WEBHOOK`	Custom HTTP webhook	`url`
`SLACK`	Slack workspace integration	`webhookUrl`
`DISCORD`	Discord server integration	`webhook_url`
`TELEGRAM`	Telegram bot notifications	`bot_token`, `chat_id`
`TEAMS`	Microsoft Teams integration	`webhook_url`
`SMS`	SMS text messages	`phone_number` (E.164 format)
`VOICE`	Voice call alerts	`phone_number` (E.164 format)

List Alert Channels

GET/api/alert-channels

Retrieve all alert channels for the authenticated user

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Success Response (200 OK):

{
  "alertChannels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "user-uuid",
      "type": "SLACK",
      "config": {
        "webhookUrl": "https://hooks.slack.com/services/T00/B00/XXX"
      },
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "user_id": "user-uuid",
      "type": "EMAIL",
      "config": {
        "email": "ops@example.com"
      },
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-01-10T08:00:00Z"
    }
  ]
}

Create Alert Channel

POST/api/alert-channels

Create a new alert channel

Headers:

Header	Value
Authorization	`Bearer {access_token}`
Content-Type	application/json

Request Body:

Field	Type	Required	Description
`type`	string	Yes	Channel type (see supported types)
`config`	object	Yes	Type-specific configuration

Configuration by Type

EMAIL

{
  "type": "EMAIL",
  "config": {
    "email": "alerts@example.com"
  }
}

WEBHOOK

{
  "type": "WEBHOOK",
  "config": {
    "url": "https://your-server.com/webhook/alerts"
  }
}

Webhook URLs must be publicly accessible. Private/internal IP addresses (localhost, 10.x.x.x, 192.168.x.x, etc.) are blocked for security reasons.

Webhook Payload:

{
  "monitor": {
    "id": "monitor-uuid",
    "name": "Production API",
    "url": "https://api.example.com/health",
    "type": "HTTPS"
  },
  "status": "DOWN",
  "error": "Connection timeout after 10000ms",
  "checkedAt": "2024-01-15T10:30:00Z"
}

SLACK

{
  "type": "SLACK",
  "config": {
    "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

Create a Slack Incoming Webhook at: https://api.slack.com/messaging/webhooks

DISCORD

{
  "type": "DISCORD",
  "config": {
    "webhook_url": "https://discord.com/api/webhooks/000000000000000000/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

{
  "type": "TELEGRAM",
  "config": {
    "bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
    "chat_id": "-1001234567890"
  }
}

Create a Telegram bot via @BotFather. The chat_id can be a user ID, group ID, or channel ID (prefix group/channel with -100).

TEAMS (Microsoft Teams)

{
  "type": "TEAMS",
  "config": {
    "webhook_url": "https://outlook.office.com/webhook/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX@XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/IncomingWebhook/..."
  }
}

SMS

{
  "type": "SMS",
  "config": {
    "phone_number": "+14155551234"
  }
}

VOICE

{
  "type": "VOICE",
  "config": {
    "phone_number": "+14155551234"
  }
}

Phone numbers must be in E.164 format: + followed by country code and number (e.g., +14155551234 for US numbers). No spaces, dashes, or parentheses.

Success Response (201 Created):

{
  "alertChannel": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "user_id": "user-uuid",
    "type": "SLACK",
    "config": {
      "webhookUrl": "https://hooks.slack.com/services/T00/B00/XXX"
    },
    "created_at": "2024-01-15T12:00:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}

Error Responses:

Status	Error	Description
400	`Email address is required`	Missing email for EMAIL type
400	`Webhook URL is required`	Missing URL for WEBHOOK type
400	`Slack webhook URL is required`	Missing webhookUrl for SLACK
400	`Discord webhook URL is required`	Missing webhook_url for DISCORD
400	`Telegram bot token is required`	Missing bot_token for TELEGRAM
400	`Telegram chat ID is required`	Missing chat_id for TELEGRAM
400	`Microsoft Teams webhook URL is required`	Missing webhook_url for TEAMS
400	`Phone number is required`	Missing phone_number for SMS/VOICE
400	`Phone number must be in E.164 format`	Invalid phone format
400	`Invalid webhook URL: Hostname 'localhost' is not allowed`	SSRF protection
400	`Invalid webhook URL: IP address is in a private/internal range`	SSRF protection

Update Alert Channel

PUT/api/alert-channels/:id

Update an existing alert channel's configuration

Path Parameters:

Parameter	Type	Description
`id`	UUID	Alert channel ID

Headers:

Header	Value
Authorization	`Bearer {access_token}`
Content-Type	application/json

Request Body:

Field	Type	Required	Description
`config`	object	No	Updated configuration

Request Example:

{
  "config": {
    "webhookUrl": "https://hooks.slack.com/services/T00/B00/NEW-HOOK"
  }
}

Success Response (200 OK):

{
  "alertChannel": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "user-uuid",
    "type": "SLACK",
    "config": {
      "webhookUrl": "https://hooks.slack.com/services/T00/B00/NEW-HOOK"
    },
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-16T14:00:00Z"
  }
}

Delete Alert Channel

DELETE/api/alert-channels/:id

Delete an alert channel

Path Parameters:

Parameter	Type	Description
`id`	UUID	Alert channel ID

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Success Response (200 OK):

{
  "message": "Alert channel deleted"
}

Test Alert Channel

POST/api/alert-channels/:id/test

Send a test notification to verify the channel works

Path Parameters:

Parameter	Type	Description
`id`	UUID	Alert channel ID

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Success Response (200 OK):

{
  "success": true,
  "message": "Test alert sent to SLACK channel"
}

For email channels:

{
  "success": true,
  "message": "Test email sent to alerts@example.com"
}

Error Responses:

Status	Error	Description
404	`Alert channel not found`	Invalid ID or not owned by user
500	Error message	Failed to send test (details in message)

Always test your alert channels after creating them to ensure notifications are delivered correctly.

Test Email Directly

POST/api/alert-channels/test-email

Send a test email without creating an alert channel

Headers:

Header	Value
Authorization	`Bearer {access_token}`
Content-Type	application/json

Request Body:

{
  "email": "test@example.com"
}

Success Response (200 OK):

{
  "success": true,
  "message": "Test email sent to test@example.com"
}

Security: SSRF Protection

To prevent Server-Side Request Forgery (SSRF) attacks, webhook URLs are validated against private/internal IP ranges.

Blocked Hostnames:

localhost
0.0.0.0
*.local
*.localhost
*.internal

Blocked IP Ranges:

127.0.0.0/8 (Loopback)
10.0.0.0/8 (Private)
172.16.0.0/12 (Private)
192.168.0.0/16 (Private)
169.254.0.0/16 (Link-local, includes AWS metadata)
::1 (IPv6 Loopback)
fe80::/10 (IPv6 Link-local)
fc00::/7 (IPv6 Private)

Alert Message Format

Down Alert

When a monitor goes down, alerts include:

Field	Description
Monitor Name	Name of the failing monitor
Monitor URL	The URL being monitored
Monitor Type	HTTP, HTTPS, TCP, etc.
Status	DOWN
Error	Specific error message
Checked At	Timestamp of the failing check

Recovery Alert

When a monitor recovers:

Field	Description
Monitor Name	Name of the recovered monitor
Monitor URL	The URL being monitored
Status	UP
Downtime Duration	How long the monitor was down
Checked At	Timestamp of the recovery check

Error Responses Summary

Status	Error	Description
400	Validation errors	Missing or invalid configuration
400	`Invalid webhook URL: *`	SSRF protection triggered
404	`Alert channel not found`	Invalid ID or not owned by user
500	`Failed to fetch/create/update/delete alert channel`	Server error
500	`Failed to send test alert`	Test notification failed