Notifications.

A notification channel is a place where NaN tells you what your automations are doing, so you do not have to keep the portal open: a Slack channel, a Microsoft Teams channel, a Discord channel or an HTTPS endpoint of your own. You add the channel once, pick the events it receives, and NaN posts a short message with a link back to the portal every time one of them happens.

Only automation runs notify. A run you start yourself with nan run or from a workspace’s Runs tab never sends a notification.

The short version: get a webhook URL from Slack, Microsoft Teams or Discord, then add the channel in Settings → Notifications and press Test.

Notifications are being opened gradually. If you do not see Notifications in Settings, your account does not have them yet.

Channels

Every channel has:

You can have up to 10 channels. Each one sends a message in the format its provider expects:

Get a Slack webhook URL

1. Go to api.slack.com/apps, press Create New App, From scratch, name it (for example NaN) and pick your workspace.
2. In Incoming Webhooks, switch Activate Incoming Webhooks on.
3. Press Add New Webhook to Workspace, pick the channel and press Allow.
4. Copy the Webhook URL. It looks like https://hooks.slack.com/services/T…/B…/….

Get a Microsoft Teams webhook URL

Teams posts webhooks through its Workflows app:

1. In the Teams channel, open … (more options) and choose Workflows.
2. Pick the template Post to a channel when a webhook request is received (in some tenants, Send webhook alerts to a channel), name it and confirm the team and the channel.
3. Copy the URL Teams shows at the end. It is on a host ending in logic.azure.com, powerplatform.com or webhook.office.com.

NaN sends an adaptive card, which is what that template posts. The URL of an old Incoming Webhook connector (on webhook.office.com) is still accepted, but Microsoft is retiring those connectors: use Workflows.

Get a Discord webhook URL

1. In Discord, open Server Settings, then Integrations, then Webhooks. You need the Manage Webhooks permission.
2. Press New Webhook and open the webhook it creates. Name it, pick the channel and press Copy Webhook URL. It looks like https://discord.com/api/webhooks/…/….

Your own HTTPS endpoint

Any https URL on port 443 with a public DNS name. NaN signs every request with a signing secret it creates for the channel and shows you once, when you create the channel: see Verify the signature. Slack, Teams and Discord channels have no signing secret.

Events

A cancelled run never notifies, and neither does a run you start yourself (outside an automation). run.finished is off by default because a busy automation would post on every run: turn it on where you want it.

For all your automations, or for one. Every event of a channel is either for all your automations (including the ones you create later) or for one automation. When you create a channel you can scope its default events to one automation, and later mix both: for example, run.failed for every automation and run.finished only for nightly report. A channel takes up to 50 of these subscriptions. Deleting an automation removes the subscriptions that named it.

The same event is sent once per channel, even when the channel is subscribed to it for all automations and for that one.

Approval messages

An approval.pending message tells you what is waiting, so you can decide whether to open it now:

• the automation and its workspace;
• when the approval expires, as a UTC time and how long is left, for example 2026-10-15 10:00 UTC (in 24 h);
• the action kinds the automation sends for approval;
• up to 5 actions waiting for approval, each as its kind and target: github_pr_comment on acme/api#342, git_push to branch fix/login, github_add_labels on acme/api#12: 2 labels. When there are more, the list ends with and 3 more.

Its Review and approve button (a bold link in Discord) opens the run in the portal with the proposed actions in view and focused: the link ends in ?approval=1, and it still works when you have to sign in first. There you review the full actions, with comment bodies and the diff, and press Approve and apply or Reject. You never approve from Slack, Teams or Discord: the message only takes you to the portal.

If the approval was decided or expired before the message went out, the message says it is no longer pending and the button becomes View run. The run page shows the same: what happened, without Approve or Reject.

Manage channels in the portal

Your channels are in your settings at cloud.nan.builders: open Settings, then Notifications, right below Secrets. Each automation’s settings also have a Notifications card that lists the channels covering it, with Manage notifications to come here.

Add a channel

1. Press Add channel. In Where, pick Slack, Microsoft Teams, Discord or HTTPS endpoint.
2. Type a Name and paste the URL in the URL field of that kind (Slack URL, for example). Where to get it: Slack, Microsoft Teams, Discord or your own endpoint.
3. Check the Events: Approval needed, Run failed, Automation turned off and Webhook signatures failing are on; Run succeeded is off, turn it on if you want it. In Automations, keep All automations, including new ones or pick one.
4. Save. For an HTTPS endpoint the portal shows the signing secret once: copy it to your endpoint’s secret store now, it is never shown again.

Then press Test: NaN sends a test message right away and tells you whether it arrived.

Test, change, rotate, delete

• Test sends a test message to the channel. It works only on a channel that is on, and you can send up to 5 in a row, then about one a minute. For Teams, delivered means the workflow accepted the message: the workflow then posts it, and if it fails, the error is in the workflow’s run history.
• Events changes which events the channel receives, and for which automations.
• Edit renames the channel or replaces its URL (New URL (optional)). The kind cannot be changed: add a new channel instead.
• Rotate secret (HTTPS only) creates a new signing secret and shows it once. The old one keeps signing too for 24 hours, so you can update your endpoint without missing a request.
• Turn off and Turn on stop and resume a channel without deleting it.
• Delete asks you to confirm, and the channel and its subscriptions are gone for good.
• Deliveries shows the last 30 days of sends: event, status, HTTP status and error code. Never the message itself.

Each channel shows its status: On, Deliveries failing (recent sends failed, it is still on), Off (you turned it off), Turned off: failing or Turned off: URL refused (NaN turned it off, see When a channel fails).

Digests and limits

NaN keeps every channel readable and never floods a provider:

• Digests. When more than 3 notifications are due for a channel at once, or more than it may still receive in the current minute, they arrive as one digest message: how many of each event, and up to 10 of them with their links.
• Per channel: at most 30 messages a minute and 1,000 a day.
• Per account: at most 3,000 messages a day across all your channels.

Over the minute limit, messages wait and are sent the next minute (as a digest when there are several). Over a daily limit, that day’s further notifications are dropped and the deliveries log shows rate_limited. Test messages count as messages.

A notification not delivered within 24 hours is dropped: a late alert is worse than none.

When a channel fails

Each message is retried when the failure may be temporary: a timeout, a connection or TLS error, a DNS failure, 408, 429 or a 5xx. It is tried up to 5 times, after 1 minute, 5 minutes, 30 minutes and 2 hours. Any other 4xx, and any redirect, fails at once: the URL is wrong or was revoked.

Turned off after 20 failures. After 20 failed attempts in a row, the channel is turned off with the reason failing, and its pending messages are dropped. The portal shows Turned off: failing, and nan notifications ls shows it too. To fix it:

1. Check the Deliveries log for the error (http_4xx, timeout, dns and so on).
2. If the webhook was deleted or revoked at the provider, create a new one and replace the URL: that re-enables the channel.
3. If the problem was on your side and is fixed, press Turn on (or nan notifications edit NAME --enable). Then press Test.

Turning it back on or replacing the URL resets the failure count.

Turned off as invalid_url. If the URL’s host starts resolving to an address NaN refuses (a private or reserved one, see Which URLs are accepted), the channel is turned off at once with the reason invalid_url (Turned off: URL refused in the portal). Replace the URL to turn it back on.

A channel you turned off yourself (reason member, Off in the portal) stays off until you turn it on, even if you replace its URL.

Verify the signature

Every request to an HTTPS channel carries these headers, with the same signature scheme as the webhooks you send to NaN:

Accept a request when any v1= value matches and the timestamp is less than 5 minutes off. Compute the HMAC over the body exactly as received, byte for byte, before parsing it. Answer with any 2xx quickly; the response body is ignored.

To check your code: with the secret nan_nsec_test, the timestamp 1700000000 and the body {"a":1}, the signature is v1=5c39c853e058b14c0d0e29bbdeb6d0dc325318231d07d1df377a284c89ad4e01. Once your endpoint verifies signatures, press Test: the test message is signed like every other.

In bash, to check a request you saved (body in body.json):

SECRET="nan_nsec_..."              # the channel's signing secret
TS="1760436000"                    # the X-Nan-Timestamp header
SIGS="v1=...,v1=..."               # the X-Nan-Signature header
EXPECTED=$(printf '%s.' "$TS" | cat - body.json | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

NOW=$(date +%s)
if [ $((NOW - TS)) -gt 300 ] || [ $((TS - NOW)) -gt 300 ]; then echo "too old"; exit 1; fi
case ",$SIGS," in *",v1=$EXPECTED,"*) echo "valid" ;; *) echo "invalid"; exit 1 ;; esac

In Python:

import hashlib, hmac, time

SECRET = b"nan_nsec_..."

def verify(body: bytes, timestamp: str, signature_header: str) -> bool:
    try:
        ts = int(timestamp)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - ts) > 300:
        return False
    expected = hmac.new(SECRET, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return any(
        part.startswith("v1=") and hmac.compare_digest(part[3:], expected)
        for part in signature_header.split(",")
    )

# In your handler, with the raw body:
# verify(request_body, headers["X-Nan-Timestamp"], headers["X-Nan-Signature"])

In Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';

const secret = process.env.NAN_SIGNING_SECRET; // nan_nsec_...

function verify(body, timestamp, header) {
  const ts = Number(timestamp);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const expected = Buffer.from(createHmac('sha256', secret).update(`${timestamp}.`).update(body).digest('hex'));
  return (header ?? '').split(',').some((part) => {
    const got = Buffer.from(part.trim().replace(/^v1=/, ''));
    return part.trim().startsWith('v1=') && got.length === expected.length && timingSafeEqual(got, expected);
  });
}

createServer((req, res) => {
  const chunks = [];
  req.on('data', (c) => chunks.push(c));
  req.on('end', () => {
    const body = Buffer.concat(chunks);
    if (!verify(body, req.headers['x-nan-timestamp'], req.headers['x-nan-signature'])) {
      res.writeHead(401).end();
      return;
    }
    const event = JSON.parse(body);
    console.log(event.event, event.text, event.url);
    res.writeHead(204).end();
  });
}).listen(8080);

Delivery is at least once: the same notification can arrive twice (for example after a network error once it was already received). Ignore an X-Nan-Delivery you have already processed.

Payload

An HTTPS channel receives POST requests with Content-Type: application/json and User-Agent: NaN-Notifications/1. The body has version: 1, and fields that do not apply to an event are null:

{
  "version": 1,
  "id": "…",
  "event": "run.failed",
  "created_at": "2026-10-14T10:00:00Z",
  "automation": { "id": "…", "name": "PR review" },
  "run": {
    "id": "…",
    "state": "failed",
    "error_code": "agent_failed",
    "phase": "propose",
    "summary": "Reviewed PR #42: two issues found in pkg/foo."
  },
  "workspace": { "id": "…", "name": "backend-ws" },
  "trigger": null,
  "reason": null,
  "approval": null,
  "url": "https://cloud.nan.builders/workspaces/…/runs/…",
  "actions_url": "https://cloud.nan.builders/workspaces/…/runs/…",
  "approve_url": null,
  "text": "Run failed: PR review (agent_failed)"
}

An approval.pending body adds the workspace, the approval and both links:

{
  "version": 1,
  "id": "…",
  "event": "approval.pending",
  "created_at": "2026-10-14T10:00:00Z",
  "automation": { "id": "…", "name": "PR review" },
  "workspace": { "id": "…", "name": "backend-ws" },
  "run": { "id": "…", "state": "awaiting_approval", "error_code": null, "phase": "propose", "summary": null },
  "trigger": null,
  "reason": null,
  "approval": {
    "state": "pending",
    "expires_at": "2026-10-15T10:00:00Z",
    "approval_kinds": ["git_push", "github_pr_comment", "github_add_labels"],
    "actions": [
      { "kind": "github_pr_comment", "target": "helmcode/nan-cloud-api#342", "text": "github_pr_comment on helmcode/nan-cloud-api#342" },
      { "kind": "git_push", "target": "nan/fix-tests", "text": "git_push to branch nan/fix-tests" },
      { "kind": "github_add_labels", "target": "helmcode/nan-cloud-api#12", "text": "github_add_labels on helmcode/nan-cloud-api#12: 2 labels" }
    ],
    "actions_total": 3
  },
  "url": "https://cloud.nan.builders/workspaces/…/runs/…",
  "actions_url": "https://cloud.nan.builders/workspaces/…/runs/…?approval=1",
  "approve_url": "https://cloud.nan.builders/workspaces/…/runs/…?approval=1",
  "text": "Approval needed: PR review"
}

A digest groups several notifications:

{
  "version": 1,
  "id": "…",
  "event": "digest",
  "created_at": "2026-10-14T10:00:00Z",
  "count": 3,
  "events": { "approval.pending": 1, "run.failed": 2 },
  "items": [
    {
      "event": "run.failed",
      "automation": { "id": "…", "name": "PR review" },
      "run": { "id": "…", "state": "timed_out", "error_code": "timed_out", "phase": "propose", "summary": "…" },
      "url": "https://cloud.nan.builders/workspaces/…/runs/…"
    }
  ],
  "url": "https://cloud.nan.builders/automations",
  "text": "3 notifications: 1 approval needed, 2 runs failed"
}

count is how many notifications it groups, events how many of each, and items up to 10 of them (the example shows one).

A test message:

{
  "version": 1,
  "id": "…",
  "event": "test",
  "created_at": "2026-10-14T10:00:00Z",
  "url": "https://cloud.nan.builders/settings#notifications",
  "text": "Test notification from NaN"
}

New fields may be added to version 1; ignore the ones you do not know.

Security

URLs are credentials

Anyone who has a Slack, Teams or Discord webhook URL can post to that channel, so NaN treats every channel URL like a secret:

• It is write-only: encrypted with a key that belongs to your account alone, and never returned by the portal, the CLI or the API. You see a hint instead, the host and the last 4 characters of the path: hooks.slack.com/…/abcd.
• It never appears in an error, a log or the deliveries list.
• From the CLI it is read from a file or a pipe, never from the command line.

If a webhook URL leaks, delete the webhook at the provider, create a new one and replace the URL in NaN.

What a message never carries

Messages carry names, states, error codes, ids and links. They never carry:

• the value of any secret, or a channel URL;
• the body or headers of the webhook request that started a run;
• the agent’s output, beyond the run’s short summary (at most 280 characters, with secrets masked);
• the bodies, titles and commit messages of proposed actions, their labels or the diff: an approval lists only kinds and targets.

Member text (an automation’s or workspace’s name, a summary, a branch) is escaped for each provider: it cannot mention anyone, ping a role or form a link.

Which URLs are accepted

NaN’s servers call these URLs, so they follow strict rules, checked when you save the URL and again on every send:

• https only, on port 443. No user or password in the URL, no fragment, no IP address: a DNS name with at least two labels.
• Not NaN’s own hosts (nan.builders, helmcode.com and their subdomains), and not local names (localhost, .local, .internal, .lan, .home.arpa, .svc).
• Every address the name resolves to must be public: private, loopback, link-local, shared and reserved addresses are refused, and so are NaN’s own.
• Slack URLs must be on hooks.slack.com with a path starting /services/. Teams URLs on a subdomain of webhook.office.com, logic.azure.com or powerplatform.com. Discord URLs on discord.com (or discordapp.com, canary.discord.com, ptb.discord.com) with a path starting /api/webhooks/.
• Redirects are not followed: a 3xx is a failure.

A refused URL gets one generic error that names the rule it breaks, never what you sent, and a name that does not resolve gets the same answer as one that resolves to a refused address.

Manage channels from the CLI

With the NaN CLI 0.1.34 or newer, where your account has notifications and the write API:

nan notifications ls                                        # kind, name, URL hint, status
nan notifications add "team alerts" --kind slack --url-file ./slack-url.txt
pbpaste | nan notifications add "ops endpoint" --kind https --url-stdin --event run.failed --event run.finished
nan notifications add "nightly" --kind discord --url-file ./discord-url.txt --automation "nightly report"
nan notifications show "team alerts"
nan notifications test "team alerts"
nan notifications subscriptions "team alerts"                # list them
nan notifications subscriptions "team alerts" --add "run.finished=nightly report"
nan notifications subscriptions "team alerts" --set run.failed --set approval.pending
nan notifications edit "team alerts" --url-file ./new-url.txt
nan notifications edit "team alerts" --enable
nan notifications rotate "ops endpoint"                     # prints the new signing secret once
nan notifications deliveries "team alerts" --limit 50
nan notifications rm "team alerts"

• The URL never goes on the command line, where it would stay in your shell history. --url-file PATH reads it from a file, --url-stdin from a pipe. There is no --url flag.
• add takes the default events unless you pass --event (repeatable, or comma-separated) or --no-events; --automation (a name or an id) scopes them to one automation.
• For an HTTPS channel, add and rotate print the signing secret once, with a reminder to store it now. With --json it is inside the JSON, as signing_secret.
• subscriptions without flags lists them. EVENT alone means all your automations, EVENT=AUTOMATION one of them. --set replaces the whole set, --add and --remove change it, --clear removes them all.
• edit changes the name (--name), switches the channel on or off (--enable, --disable) or replaces the URL. Replacing the URL or --enable re-enables a channel NaN switched off and resets its failure count.
• test exits with code 0 when the message was delivered and 1 when it was not, with the reason.
• deliveries shows the last 20 sends by default (--limit 1 to 100).
• rm asks before deleting; --yes skips the question in scripts.
• Commands take a channel’s name or its id, and --json prints JSON.
• Where your account does not have notifications or the write API, the commands say so, point you to the portal and exit with code 64. A refused credential or scope exits with 65, and a rate limit or a server error with 69.

With a platform token, the commands need notifications:read to list or show channels (and to find one by name) and notifications:write to change them; --automation with a name also needs automations:read.

The full list of flags is in nan notifications --help.

Manage channels from the API

The same operations are in the API, under https://api.nan.builders/v1/notification-channels:

Which credentials work: your CLI session from nan auth login, or a platform token with the scope of the route. The two scopes are independent: notifications:write does not include notifications:read. A token with a notifications: scope can only be created in the portal, Settings → Tokens (the scopes are in their own Notifications group), signed in through your browser, and they are offered there only where your account has notifications and the write API. An API key (sk-...) and the key inside a workspace are refused. Where your account does not have notifications or the write API, every route answers 404.

Create a channel from a file, so the URL never appears in your shell history:

jq -n --rawfile u slack-url.txt '{name: "team alerts", kind: "slack", url: ($u | rtrimstr("\n"))}' |
  curl https://api.nan.builders/v1/notification-channels \
    -H "Authorization: Bearer $NAN_TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @-

The answer is the channel, never its URL:

{
  "id": "…",
  "object": "notification_channel",
  "name": "team alerts",
  "kind": "slack",
  "url_hint": "hooks.slack.com/…/abcd",
  "enabled": true,
  "disabled_reason": null,
  "consecutive_failures": 0,
  "last_delivery_at": null,
  "last_delivery_status": null,
  "subscriptions": [
    { "event": "approval.pending", "automation_id": null },
    { "event": "run.failed", "automation_id": null },
    { "event": "automation.disabled", "automation_id": null },
    { "event": "trigger.failing", "automation_id": null }
  ],
  "signing": null,
  "updated_by": "platform_token",
  "created_at": "…",
  "updated_at": "…"
}

• disabled_reason is null, member (you disabled it), failing or invalid_url. signing is {"previous_expires_at"} on https channels: when the old secret stops signing after a rotation.
• updated_by says where the last change came from: browser_session, cli_session or platform_token.
• Errors come as {"error": {"message", "type", "param", "code"}}. param names the field that is wrong and never repeats what you sent.
• Rate limits. Changes to channels (create, edit, delete, subscriptions, rotate) share one allowance per account: a burst of 30, then 120 per hour, counting the portal, the CLI and the API. Tests have their own: up to 5 in a row, then 1 a minute. Beyond them, 429 rate_limited.

Every route, body and error is in API reference → Notifications.

Limits

If something goes wrong