Relay API
Base URL: https://relay.example
1. Webhook URL
Create a webhook in the dashboard and send any of the following to it. POST, PUT and GET are accepted. Body limit 64 KB.
POST /h/{token}
Content-Type: application/json
{
"title": "Disk 92% on db-1",
"text": "Free space below 8%",
"severity": "high", // info | low | medium | high | critical (also: warning, error, fatal, p1…)
"url": "https://grafana.example/d/abc",
"fields": { "host": "db-1", "region": "ap-northeast-2" },
"dedup_key": "disk-db-1", // optional, repeated keys are suppressed inside the window
"status": "firing" // "resolved" / "ok" sends a ✅ message and clears the duplicate window
}
Plain text works too:
curl -d 'Backup finished in 42s' https://relay.example/h/{token}
curl 'https://relay.example/h/{token}?text=Server%20rebooted&severity=medium'
Auto-detected formats: Prometheus Alertmanager, Grafana alerting, GitHub (set the webhook content type to application/json), Uptime Kuma (Webhook, JSON), SentinelClause Guard events, generic JSON and plain text. Force a format with ?format=alertmanager or in the webhook settings.
Signed webhooks
If “Require HMAC signature” is on, send X-Relay-Signature: sha256=<hex HMAC-SHA256(raw body, signing secret)>. GitHub’s X-Hub-Signature-256 is also accepted, so you can use the signing secret as the GitHub webhook secret.
2. REST API
POST /v1/send
Authorization: Bearer rk_…
Content-Type: application/json
{
"title": "Deploy finished",
"text": "v2.3.1 is live",
"severity": "info",
"channels": ["ch_…"], // optional: chat ids from the dashboard, Telegram chat ids or chat titles. Default: all active chats
"hook": "hk_…", // optional: use a webhook's routing, filters and mute state
"buttons": true // Acknowledge / Mute buttons
}
→ 202 { "ok": true, "queued": 1, "messages": ["msg_…"] }
GET /v1/messages/{id}
Authorization: Bearer rk_…
→ { "ok": true, "message": { "status": "sent", "attempts": 1, "ack_by": "@ops", … } }
3. Responses
| Status | Meaning |
|---|---|
| 202 | Queued. Delivery normally completes within a second; failures retry automatically up to 8 times. |
| 200 | Accepted but not sent: suppressed (duplicate or muted), filtered (below minimum severity) or ignored (event type not relevant). |
| 400 / 401 / 404 | Invalid body, bad API key or signature, unknown webhook. |
| 402 | Monthly message limit reached. |
| 409 | No active chat to deliver to. |
| 429 | Per-minute limit of your plan exceeded. |
4. In Telegram
✅ Acknowledge marks the alert handled and shows who did it. 🔕 Mute 1h silences that webhook for an hour for everyone. Bot commands: /status, /channels, /login, /link CODE, /help.
5. Examples
# Prometheus Alertmanager
receivers:
- name: telegram
webhook_configs:
- url: https://relay.example/h/{token}
send_resolved: true
# Grafana: Alerting → Contact points → Webhook → URL = https://relay.example/h/{token}
# GitHub Actions step
- run: curl -fsS -X POST "$RELAY_URL" -H 'content-type: application/json' \
-d "{\"title\":\"${{ github.workflow }} ${{ job.status }}\",\"severity\":\"${{ job.status == 'success' && 'info' || 'high' }}\"}"
# Node.js
await fetch('https://relay.example/v1/send', { method: 'POST',
headers: { authorization: 'Bearer ' + process.env.RELAY_KEY, 'content-type': 'application/json' },
body: JSON.stringify({ title: 'New signup', text: user.email }) });
# Python
requests.post(RELAY_URL, json={"title": "Job failed", "severity": "critical"})