telegram-notify-service

Tiny HTTP service (Go) to send notifications to Telegram.

Production URL: https://telegram-notify-service-production.up.railway.app

Features

• POST /api/v1/notify — sends a formatted Telegram message (HTML + emoji)
• GET /api/v1/healthz — healthcheck endpoint
• ADMIN_TOKEN protection (Bearer token / X-Admin-Token)
• Docker-friendly (distroless runtime image)

Endpoints

POST /api/v1/webhooks/vk

VK Callback API webhook receiver.

• If VK sends { "type": "confirmation" } the service returns VK_CONFIRMATION_TOKEN as plain text.
• For other events, it responds with plain text ok and triggers an internal call to POST /api/v1/notify.
• Optional validation: if VK_SECRET is set, incoming payload must include the same secret.

GET /api/v1/healthz

Returns 200 ok.

POST /api/v1/notify

Sends message to Telegram using parse_mode=HTML.

Request body:

{
  "text": "Deploy failed on migrations",
  "title": "Prod deploy failed",
  "level": "error",
  "source": "payments-api",
  "links": [{ "label": "Logs", "url": "https://example.com/logs" }]
}

Supported fields:

• text (string, required)
• title (string, optional)
• level ("info" | "warning" | "error" | "success", optional; default: "info")
• source (string, optional)
• links (array, optional) — { label, url }
• timestamp (ISO-8601 string, optional)

Configuration

Environment variables:

• TELEGRAM_BOT_TOKEN (required)
• TELEGRAM_CHAT_ID (required)
• ADMIN_TOKEN (required)
• PORT (optional, default: 8080)

See: .env.example

Run locally

export TELEGRAM_BOT_TOKEN="..."
export TELEGRAM_CHAT_ID="..."
export ADMIN_TOKEN="..."
export PORT=8080

go run ./cmd/server

Test request:

curl -X POST https://telegram-notify-service-production.up.railway.app/api/v1/notify \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <ADMIN_TOKEN>' \
  -d '{
    "text": "Deploy failed on migrations",
    "title": "Prod deploy failed",
    "level": "error",
    "source": "payments-api",
    "links": [{"label":"Logs","url":"https://example.com/logs"}]
  }'

Run with Docker

docker build -t telegram-notify-service .

docker run --rm -p 8080:8080 \
  -e TELEGRAM_BOT_TOKEN="..." \
  -e TELEGRAM_CHAT_ID="..." \
  -e ADMIN_TOKEN="..." \
  telegram-notify-service

Notes

• Telegram message delivery is synchronous: POST /api/v1/notify returns error if Telegram API responds with an error.
• For production, consider adding rate limiting and deduplication depending on your alert sources.