Webhook Notifications

Cassian™ can POST notification events to a URL you specify. This lets you route alerts into Slack, Discord, or any custom system that can receive HTTP requests.

Endpoint requirements

• HTTPS only — plain HTTP URLs are rejected
• Publicly reachable — private and internal addresses are blocked
• No redirects — Cassian does not follow redirect responses; a 3xx counts as a failed delivery
• Respond with a 2xx status within 10 seconds

What Cassian auto-detects

Cassian inspects the URL you provide and adjusts the payload format automatically:

You don't need to configure the format — Cassian detects it from the URL.

Setting up a Slack webhook

Setting up a Discord webhook

Testing your webhook

Saving a webhook does not automatically send anything. Use the Send test button next to your webhook in Settings — Cassian delivers a sample notification immediately so you can confirm the connection works before relying on it. Tests are rate-limited to 6 per minute.

The JSON payload (for custom endpoints)

For any URL that isn't a recognised Slack or Discord webhook, Cassian sends a generic JSON payload:

{
  "id": "uptime-3f8a1c2e-...",
  "source": "uptime",
  "severity": "critical",
  "title": "Your Store is down",
  "body": "Your Store returned HTTP 503.",
  "actionUrl": "https://app.getcassian.com/dashboard/uptime",
  "siteId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "timestamp": "2026-02-26T10:00:00Z"
}

Recovery events (store back up, orders flowing again) arrive from the same source with severity info.

Verifying webhook authenticity

For generic endpoints with a secret configured, every request includes an X-Cassian-Signature header in the form sha256=<hmac_hex> — an HMAC-SHA256 signature of the raw request body, signed with your webhook secret. Slack and Discord deliveries are not signed (those platforms don't support custom verification headers).

Your webhook secret is shown in full when it is first generated; after that, Settings shows only a truncated prefix. Keep a copy somewhere safe — anyone with it can forge requests that look like they came from Cassian.

Example verification (Node.js):

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  // Header format: "sha256=<hex>"
  if (!signatureHeader || !signatureHeader.startsWith('sha256=')) {
    return false;
  }
  const received = Buffer.from(signatureHeader.slice('sha256='.length), 'hex');
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody) // must be the raw request body, before any JSON parsing
    .digest();
  if (received.length !== expected.length) return false;
  return crypto.timingSafeEqual(received, expected);
}

Two things matter here: compute the HMAC over the raw request body exactly as received (re-serialising parsed JSON can change the bytes), and length-check before calling timingSafeEqual (it throws on mismatched lengths).

Delivery failures and auto-disable

• Failed deliveries are retried up to 2 times.
• After 5 consecutive failed alerts, the webhook is automatically disabled.
• If your endpoint returns 403, 404, or 410, the webhook is disabled immediately — those responses mean the endpoint is gone or refusing Cassian, and retrying won't help.
• To re-enable a disabled webhook, re-save the URL in Settings → Notifications (then use Send test to confirm it's healthy).

Frequently asked questions

Can I have multiple webhooks?

No — each organisation has one webhook. If you need alerts in several places, point the webhook at your own endpoint and fan out from there, or use Telegram and email alongside it.

My Slack webhook isn't formatting correctly — why?

Confirm you're using a Slack Incoming Webhooks URL (it starts with https://hooks.slack.com/services/). App-level webhook URLs from Slack's API are different and won't trigger Cassian's Block Kit formatting.

How do I find my webhook secret?

The full secret is shown once, when it's first generated in Settings → Notifications. Afterwards only a truncated prefix is displayed. If you've lost it, you'll need to generate a fresh secret — the old one stops working once replaced.

Can I filter which events go to the webhook?

Yes. The What to send where matrix in Settings → Notifications lets you toggle each event source for the webhook channel, and you can set a minimum severity for the channel (for example, warning and above only).

What happens if my webhook endpoint is down?

Cassian retries the delivery up to 2 times. After 5 consecutive failed alerts — or immediately on a 403/404/410 response — the webhook is disabled. Re-save the URL in Settings once your endpoint is back online to re-enable it.

Can I use a webhook to trigger an automation or script?

Yes. Any HTTPS endpoint that can receive an HTTP POST and return a 2xx status within 10 seconds will work. Common uses include triggering deploys, updating project management tools, or logging to your own monitoring system.