Notifications

This page is for the administrator. It explains what a notification is, how to have notifications sent to a webhook and by mail from the Notification delivery page, and what each kind of notification means.

What a notification is

The server does some things by itself: it publishes queued posts at their time, reads watched accounts, pushes leads, checks alert rules and builds scheduled reports. When one of those needs a person, the server writes a notification.

A notification always goes to its owner's Notifications page first. That page is the notification. A webhook and mail are extra ways to reach someone who is not looking, and you set them up once for the whole installation.

• Each person sees only their own notifications. The Notifications entry in the sidebar shows a mark while there are unread ones.
• A person's AI client can read their notifications too, and is asked to tell them about the unread ones.
• A notification names the server's own posts, accounts and settings. It never carries a customer's details or anyone's comment.
• A notification only tells. The server does not act on one, and does not try the failed thing again.

On the Notifications page each one shows Needs you, Needs a look or For your information until it is read. Mark read and Mark all read clear them, and Open goes to the page of the management page that the notification is about.

Set up the webhook

With a webhook, every notification of every person is also sent to one address, as JSON. Use it to pass notifications on to a chat channel or an automation tool.

1. Open Notification delivery.
2. Under Webhook, type the address in Webhook URL, such as https://hooks.example.com/marketing.
3. Type a secret in Signing secret. It is optional, and recommended: see Check the signature.
4. Press Save delivery settings.
5. Press Send a test and read what the webhook answered.

It takes effect at once. The heading What is sent shows Delivering when a webhook or a mail server is set, and This site only when neither is.

What the address must be

• It must start with https:// and be a public address. An address on this machine or its own network is refused.
• It must not carry a username or a password.
• A redirect is never followed. If the test says the webhook answered with a redirect, save the address that it finally lives at.
• Only this page, or an environment variable, can set the address. No AI client can set or change where the server sends.

The address is checked again every time something is sent, not only when you save it.

A receiver on your own network

If the receiver is on the server's own machine or network, tick Allow a private address. Then the address is not checked. HTTPS is still required, unless the address is this machine itself (localhost).

What is sent

Each notification is one POST request with a JSON body:

{
  "kind": "queue_failed",
  "severity": "warning",
  "title": "...",
  "body": "...",
  "link": "https://ads.example.com/#/queue",
  "username": "sara",
  "at": "2026-10-10T03:00:12+00:00"
}

Field	What it holds
kind	The kind of notification, from the table in What is told, and when. The test sends test.
severity	info, warning or error.
title	One line.
body	What happened, and what it asks of the person.
link	The page of the management page that it is about, or nothing.
username	Whose notification it is. Empty for a notice about the installation.
at	When it was written, in UTC.

Your receiver should answer with a 2xx status. The server tries once and waits about ten seconds. Any other answer, or no answer, is noted on the notification as Not delivered with the reason. Nothing is sent again.

Check the signature

With a Signing secret, every request carries the header X-Nama-Signature. Its value is sha256= followed by the HMAC-SHA256 of the body, in hexadecimal, keyed with your secret. Without a secret the body is sent unsigned.

To check it, compute the same value over the exact bytes you received, before you parse them:

import hashlib
import hmac

def came_from_the_server(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

The secret is never shown again after you save it. The page only says that one is set. To change it, type a new one. To remove it, tick Remove the signing secret and save.

TIP

The lead webhook is a different address with its own secret, on the Lead delivery page. Leads are never sent to the notification webhook. See Lead delivery.

Set up mail

With a mail server, each person's notifications are also mailed to the address that they saved for themselves.

1. Open Notification delivery.
2. Under Email, fill in Mail server (SMTP) and Port.
3. Choose Security:
   • STARTTLS (usually port 587), which is the default;
   • SSL/TLS (usually port 465);
   • None - a relay on this machine only.
4. If the mail server asks for a sign-in, fill in Username and Password.
5. Type the address mail is sent from in Send from.
6. Optionally type your own address in Administrator's address.
7. Press Save delivery settings, then Send a test.

Mail is tried once the mail server and Send from are both set. The password is never shown again. To remove it, tick Remove the stored password and save.

Who gets mail

• Each person gets their own notifications at the address they save on their own Notifications page, under Also by email, in Your address. Nobody else can set it, and a person who leaves it empty gets no mail.
• The administrator's address gets a notice that is about the installation and not about one person, and the test.

A notification is mailed as plain text. Its subject starts with [Marketing MCP], and it ends with the link to the page it is about.

TIP

Tell people to save their address. Until someone does, their notifications stay on the Notifications page and go to the webhook, and nothing is mailed to them.

Send a test

Send a test sends one message through each channel and shows what each answered: Delivered, Failed with the reason, or Not set up.

• It tests what is saved, not what is typed in the boxes. Save first.
• The mail goes to the administrator's address and to your own address from the Notifications page. With neither, the test says there is nobody to send it to.
• It writes no notification.

What is told, and when

The Notification delivery page lists every kind with the sentence below it. The name in the first column is what your webhook receives in kind.

The post queue

Kind	When it is sent
queue_failed	A queued post was tried at its time and was refused, by the platform or by one of the server's own checks. It stays in the queue with the reason. Nothing tries it again.
queue_missed	A queued post's time passed while the server was not running, and the server came back too late to publish it unasked. It waits in the queue for its owner to publish or cancel.
queue_interrupted	The server stopped while a queued post was being published, so it is not known whether the post went out. Its owner has to look at the account.
queue_overdue_at_start	The server started and found queued posts whose time had already passed. One notice for each person lists them and what became of each.

See Scheduling.

Connections

Kind	When it is sent
connection_expiring	A person's Meta connection ends within 7 days, or their LinkedIn connection within 30. It is sent once for each time a connection runs out. Connecting again renews it.

See Meta and LinkedIn.

History and lead feeds

Kind	When it is sent
watch_stopped	The server was reading an account by itself and can no longer: the person's user is disabled, the connection is gone, or the platform refuses. It is sent once when the reading stops, not on every try.
lead_push_failing	The server was pushing new leads to the lead webhook and cannot: the webhook does not answer, the platform refuses, or the feed's owner may no longer read leads. It is sent once for each outage. The server keeps trying, and no lead is marked as sent.

See History and retention and Lead delivery.

Alert rules

These are the rules that each person sets for themselves. A rule only tells: nothing is paused or changed. Each is sent once when the line is crossed, and again only after a later check found it no longer crossed.

Kind	When it is sent
alert_cpl_above	An ad account's cost per lead over the rule's days is above the amount the person set.
alert_spend_no_leads	An ad account spent over the rule's days and brought no lead.
alert_ad_rejected	The platform's review rejected an ad. Each ad is named once.
alert_budget_pace	An ad account's spend this month projects to end over the person's plan, by more than the rule's margin. The projection is the server's own arithmetic, not the platform's forecast.
alert_follower_drop	A watched account's followers fell by more than the percent the person set, by the figures that the server kept.
alert_comment_spike	An account's recent posts gathered more new comments within a day than the number the person set. It is a count only: the server does not read the comments.
alert_rule_stopped	One of a person's rules cannot be checked: their user is disabled, the connection is gone, or the platform refuses. It is sent once, not at every try.

See Budgets and alerts.

Scheduled reports

A report itself is not a notification. These two say that one did not arrive.

Kind	When it is sent
report_not_delivered	A scheduled report was built and could not be delivered one of the ways the person chose: there is no mail server or they saved no address, the webhook does not answer, or the file could not be written. Nothing sends it again. Where a file could be kept, it is on their Reports page.
report_failed	A scheduled report could not be built: the person's user is disabled, or the server stopped while it was being built. It is sent once. Nothing builds it again by itself.

See Scheduled reports.

What scheduled reports use from this page

A scheduled report is delivered by the ways its owner chose, and two of them are set up here:

• by mail, to the owner's own address from their Notifications page, through this mail server;
• by webhook, to this webhook.

So a person can choose mail for a report only after you set up the mail server and they save an address. A report holds figures, so think about who reads the webhook's receiver before people choose it. See Scheduled reports.

When delivery fails

• The notification is still on its owner's Notifications page. That part does not depend on the webhook or on mail.
• The reason is shown under the notification, after Not delivered. What did go out is shown after Also sent by.
• Nothing is sent again. Fix the cause and use Send a test.

How long a notification is kept

An unread notification is kept until someone reads it. A read one is deleted 90 days after it was written. Deleting a user deletes their notifications.

Where these settings are saved

What you save here goes into config.json. Every field on this page also has an environment variable, which wins over the file. Settings lists them.