Docs menu

Operate

Alerts and signed webhooks

Get alerts in Slack, Discord, Telegram or your own webhook, with signatures you can check and automatic retries.

Explain it

CLI can tell you when something needs attention (a failed deploy, an outage, low credit, an approval waiting, a promise about to break) wherever you already work.

How to do it: open a project, go to Settings, and find Alerts. Choose Slack, Discord, Telegram or Webhook, paste the address, and press Connect. CLI sends a test message straight away so you know it works. You can also install the dashboard on your phone for notifications.

If a message doesn't get through, CLI tries again later: after a minute, 5 minutes, 30 minutes, 2 hours and 8 hours. Deliveries under each channel shows what was sent and lets you retry by hand.

For your own webhook, CLI gives you a signing secret once, when you connect it. Your code uses it to check each message really came from CLI. Copy it straight away: it isn't shown again (you can make a new one).

Channels

API
POST /v1/projects/:id/channels {"kind": "webhook", "url": "https://example.com/cli-events", "events": ["deploy_failed", "service_down"]}
GET /v1/projects/:id/channels
POST /v1/projects/:id/channels/:channel/test
DELETE /v1/projects/:id/channels/:channel

kind is slack, discord, telegram (botToken, chatId) or webhook. Up to 10 per project, admins. events defaults to the ones worth interrupting someone for; the full list is in kinds from GET. Each channel carries signed and lastDelivery {at, ok, error}.

Signatures

Creating a webhook channel returns secret (whsec_…) once. Every request to it carries:

HeaderValue
X-CLI-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
X-CLI-Eventthe event kind, e.g. deploy_failed
X-CLI-Deliverythe delivery id, the same on every retry: use it to drop duplicates
X-CLI-Attempt1 to 6

Check it against the raw body, before parsing, and reject anything more than five minutes old:

JavaScript
import crypto from "node:crypto";

function verifyCli(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const want = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const got = Buffer.from(parts.v1 ?? "", "hex");
  return got.length === want.length && crypto.timingSafeEqual(got, want);
}
python
import hashlib, hmac, time

def verify_cli(secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", 0))
    if abs(time.time() - t) > 300:
        return False
    want = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, parts.get("v1", ""))

POST /v1/projects/:id/channels/:channel/secret makes a new secret (the old one stops working at once). Webhook channels made before signing existed start unsigned; this is how they get one. Slack, Discord and Telegram don't get CLI's headers: they check the sender themselves. Redirects aren't followed.

The body is {kind, projectId, text, content, data, seq, at}; content repeats text so Discord-style receivers show it.

Retries

Every delivery to every channel is recorded before it's sent. A failure (a non-2xx answer, a timeout after 8 seconds, a connection error) is retried after 1 min, 5 min, 30 min, 2 h and 8 h: six attempts over about 10½ hours, then it's marked failed.

API
GET /v1/projects/:id/channels/:channel/deliveries
POST /v1/projects/:id/deliveries/:delivery/retry

Deliveries show status (pending, delivered, failed), attempts, nextAt and lastError, newest first. A manual retry tries once more straight away. Delivery records are kept for 7 days.