SentinelClause Relay

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

StatusMeaning
202Queued. Delivery normally completes within a second; failures retry automatically up to 8 times.
200Accepted but not sent: suppressed (duplicate or muted), filtered (below minimum severity) or ignored (event type not relevant).
400 / 401 / 404Invalid body, bad API key or signature, unknown webhook.
402Monthly message limit reached.
409No active chat to deliver to.
429Per-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"})