Skip to content

Notifications

Aperture can tell you when something happens: on the device you are using, as a push notification on your phone’s lock screen, or through ntfy, Telegram, Discord, email or a webhook. This page covers each channel, the rules that decide which events notify whom, push on phones, signed webhooks for other software, and what to check when nothing arrives.

Notifications are set up per person under Settings › Notifications. Every account, viewer or administrator, has its own channels and rules.

What it is Needs
Notify on this device An alert from the browser for every event on cameras you may see, while Aperture is open in a tab or as an installed app. Nothing else; no outside push service.
Channels and rules Rules pick which events go to which channels: Web Push (also when Aperture is closed), ntfy, Telegram, Discord, a webhook, email. A channel and a rule. Web Push needs HTTPS.
Integrations › Webhooks Every event, as signed JSON, to software such as n8n or Node-RED. Administrators only. A URL that accepts a POST. See Signed webhooks.

The common setup: an alert with a picture on your phone’s lock screen when a person is at the front door.

  1. Make Aperture reachable over HTTPS, usually through a reverse proxy, and set APERTURE_PUBLIC_URL to that address. Browsers only allow push on secure pages.
  2. On the phone, open Aperture at its HTTPS address and sign in.
    • iPhone and iPad: in Safari, choose Share › Add to Home Screen, then open Aperture from the new icon. Safari offers web push only to web apps added to the home screen, on iOS 16.4 or later. See Mobile.
    • Android: Chrome supports push in the browser; installing to the home screen is optional.
  3. In Aperture on the phone, open Settings › Notifications. Under This device, switch on Also alert when closed (Web Push) and allow notifications when the phone asks.
  4. Under Channels, select Add channel, choose Web Push, give it a name and select Add channel.
  5. Under Rules, select Add rule. Name it (“Person at the front door”), choose the camera, tick the Web Push channel under Notify via, type person in the object filter, and select Save rule.
  6. Select the send button next to the rule (“Send a test notification”). The test arrives on every device where Web Push is on.

Repeat step 3 on each phone, tablet or computer that should get the alerts. The one Web Push channel reaches all of them.

Settings › Notifications › This device › Notify on this device turns on alerts in the browser you are using. While Aperture is open (in a tab, or as an installed app that is running), every new event on a camera you may see raises a notification; clicking it opens Playback at that moment. It shows at most one alert per camera every 30 seconds.

  • It needs no outside push service, so it also works in browsers that block one.
  • It is not filtered by rules, and it keeps working while the system is disarmed.
  • It is set per device and per browser, not per account.
  • When the app is closed it delivers nothing. Use Web Push for that.

A channel is a place alerts go. Add one under Settings › Notifications › Channels › Add channel, choose its Type, give it a Name and fill in its fields.

Type Fields What Aperture sends
Web Push none A push to every device of yours that has Also alert when closed (Web Push) on, with title, time, picture and a link.
ntfy Server (default https://ntfy.sh), Topic, Access token (optional) A message to the topic, with the picture attached and a click-through link.
Telegram Bot token, Chat ID A photo with the title, time and link as caption; a text message when there is no picture.
Discord Webhook URL A message with an embed: title, time, link and picture.
Webhook POST URL {"title", "body", "url", "image"} as JSON. Not signed; see Signed webhooks for that.
Email (SMTP) SMTP host, Port (default 587), Username and Password (optional), From address, To address(es) (comma-separated) An HTML email with the title as subject, the picture and an Open in Aperture link.

Each channel has an Enabled switch, a send button that delivers a test notification, and a delete button. A channel’s settings cannot be edited after it is added, and its tokens and passwords are never shown back: to change one, delete the channel and add it again.

Aperture creates its own push keys (VAPID) on first start and keeps them in its database. A push that the device’s push service cannot deliver within two minutes (the phone is off, for example) is dropped. A device that has uninstalled the app or revoked permission is removed from the list automatically the next time a push to it fails.

Brave and some hardened browsers turn off the push service. Aperture tells you when that happens; in Brave, enable “Use Google services for push messaging” in its privacy settings and restart it.

Works with the public ntfy.sh server or your own. Use a hard-to-guess topic name on the public server: anyone who knows the topic can read it. For a protected topic, create an access token in ntfy and enter it.

Create a bot with Telegram’s BotFather to get the Bot token, send the bot a message (or add it to a group), and enter the chat’s Chat ID.

Aperture connects to the SMTP host on the given port and upgrades the connection with STARTTLS when the server offers it. Use port 587 (or 25). Port 465, which expects TLS from the first byte, does not work. A username and password are only sent over an encrypted connection.

A rule says which events notify which channels. Add one under Settings › Notifications › Rules › Add rule; the button is available once you have a channel.

Field What it does
Name and Enabled A name for the list, and a switch to pause the rule.
Cameras The cameras the rule covers. None selected means all cameras you can access.
Notify via One or more of your channels.
Cooldown Every event, 1 minute, 2 minutes (default), 5 minutes or 15 minutes. After the rule fires, it stays silent for this long.
Quiet hours From and To times (default 23:00 to 07:00) when the rule stays silent. Can span midnight.
Time of day Any time of day, Daytime only or Nighttime only, by the sunrise and sunset at your site.
Only when raining Only when the recorded weather shows precipitation at that moment.
Object filter “Only these objects, e.g. person, car (optional)”: comma-separated labels. The event must carry at least one.

Time of day and rain use your site’s location and weather, and are ignored until a location is set under Settings › Environment (see Site and weather). Quiet hours are read in the site’s time zone when one is set, otherwise in the server’s.

How a rule is checked:

  • Rules are checked once, when an event opens. Motion, audio and package events all count; through the API (eventTypes: motion, audio, package) a rule can be limited to some.
  • An object filter needs object recognition or an external detector. With a filter set, a rule never fires on plain motion. With local recognition, the event carries what was recognised in its first 1.5 seconds; something that shows up later in the same event is not seen by the rule.
  • Labels are lower case: person, car, truck, bus, motorcycle, bicycle, dog, cat, bird, horse, bear, cow, sheep, and package for package deliveries and pick-ups. An external detector uses its own label names.
  • The cooldown belongs to the rule, not to each camera. A rule covering three cameras with a 5-minute cooldown sends one alert, then nothing from any of the three for 5 minutes. Make one rule per camera if each should alert on its own.
  • If several rules match the same event, each one sends its own alert.

The send button next to a rule sends a test notification through each of its channels.

Part Example
Title “Person, car · Front door”. Without recognised objects: “Motion detected · Front door”, “Audio · Garage”, “Package delivered · Front door”.
Text The event time, for example “Mon 14:03:27”, in the server’s time zone.
Link <public URL>/playback?camera=<id>&t=<time>: opens Playback at the moment the event began.
Picture The event’s thumbnail, through a signed link.

The picture link looks like https://nvr.example.com/api/public/event-thumb?e=<event>&exp=<time>&sig=<signature>. It opens that one picture without signing in and stops working after 24 hours. The signature is an HMAC-SHA256 with a secret only the server knows, so the link cannot be changed to show another event.

Links and pictures are built from APERTURE_PUBLIC_URL. Whoever opens them must be able to reach that address: your phone (on the LAN, or through your proxy or VPN when away), and for Telegram and Discord their own servers, which fetch the picture themselves.

  • Each person’s channels and rules are their own. Administrators do not see other people’s rules in the web app.
  • A rule only fires for cameras its owner is allowed to see. An administrator’s rules cover every camera; a viewer’s rules cover only the cameras assigned to them (see Users), even if a rule was made when they had more. A disabled account’s rules deliver nothing until the account is enabled again.
  • Notify on this device follows the same camera access.
  • Automations can also send to channels, with their own triggers. They belong to administrators.

When the system is disarmed, rules deliver nothing: no Web Push, ntfy, Telegram, Discord, webhook channel or email. Events are still recorded and listed in Alarms, Notify on this device keeps working, and signed webhooks are still sent. Aperture is armed unless something disarmed it. See Arming and disarming.

Integrations › Webhooks sends every event to a URL as JSON, signed so the receiver can check it came from your Aperture. Use it for n8n, Node-RED, Home Assistant webhooks or your own service. It is separate from the Webhook notification channel, which is not signed and has no retries.

  1. Open Integrations › Webhooks and select Add webhook.
  2. Enter a Name and the URL, and select Create.
  3. Select the send button (“Send test”). The Last test column shows OK (200) or the error.

Aperture generates a random signing key for each webhook. Webhooks fire for every event regardless of arming, and each delivery is tried up to three times (after 2 and 4 seconds), each attempt with a 10-second timeout.

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Aperture-Webhook/1
X-Aperture-Signature: sha256=5f2c…
{
"type": "event",
"ts": 1763215407000,
"event": {
"id": "3f9a1c2e7b8d4e6f9a0b1c2d3e4f5a6b",
"cameraId": "b41e0c9a2f7d48e3a1c5d6e7f8091a2b",
"eventType": "motion",
"startTs": 1763215402000,
"endTs": 0,
"score": 0.034,
"topLabel": "person",
"objects": ["person"]
},
"link": "https://nvr.example.com/playback?camera=b41e0c9a2f7d48e3a1c5d6e7f8091a2b&t=1763215402000",
"thumbUrl": "https://nvr.example.com/api/events/3f9a1c2e7b8d4e6f9a0b1c2d3e4f5a6b/thumb.jpg"
}
  • eventType is motion, audio or package. The webhook is sent when the event opens, so endTs is usually 0.
  • topLabel and objects are present only when objects were recognised.
  • link and thumbUrl are present when APERTURE_PUBLIC_URL is set. thumbUrl needs authentication: fetch it with an API token that has events:read (see API).
  • ts is when the request was sent; all times are Unix milliseconds.
  • A test delivery sends {"type": "test", "message": "Aperture webhook test", "ts": …}.

X-Aperture-Signature is sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with the webhook’s secret. Compute it over the body exactly as received, before parsing the JSON, and compare in constant time.

The web app does not show the secret. Read it with an administrator’s API token (scope automation:read); each webhook in the list has a secret field:

Terminal window
curl -s -H "Authorization: Bearer apt_…" https://nvr.example.com/api/v1/webhooks

Or choose your own when you create the webhook through the API (scope automation:write), and limit it to some event types:

Terminal window
curl -s -X POST https://nvr.example.com/api/v1/webhooks \
-H "Authorization: Bearer apt_…" \
-H "Content-Type: application/json" \
-d '{"name": "n8n", "url": "https://n8n.example.com/webhook/aperture", "events": ["motion", "package"], "secret": "<long random string>", "enabled": true}'

To check a saved body by hand:

Terminal window
openssl dgst -sha256 -hmac '<secret>' -r body.json | cut -d' ' -f1

The output must equal the part of the header after sha256=.

In a Node.js receiver:

import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody: the request body as received (a Buffer), before JSON parsing.
export function verify(rawBody: Buffer, header: string | undefined, secret: string): boolean {
const expected = Buffer.from("sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex"));
const got = Buffer.from(header ?? "");
return got.length === expected.length && timingSafeEqual(got, expected);
}

In Go:

func verify(body []byte, header, secret string) bool {
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(body)
want := "sha256=" + hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(want), []byte(header))
}

The last 50 delivery attempts of a webhook, with status and HTTP code, are at GET /api/v1/webhooks/{id}/deliveries.

  • The test works but real events don’t notify. Check that the rule is enabled, covers the camera, and is not inside its quiet hours or cooldown. With an object filter, check that the event in Alarms actually carries that label. Check that the system is not disarmed.
  • “no registered devices for push”. No device has Also alert when closed (Web Push) on for your account. Turn it on, on the phone itself.
  • The Web Push switch is missing on an iPhone. It only appears in the app opened from the home screen, over HTTPS.
  • Push stops arriving on a phone. Turn Also alert when closed (Web Push) off and on again on that device to register it anew. Do the same after removing and re-adding the app to the home screen.
  • Telegram tests arrive but event alerts don’t. Tests carry no picture; event alerts send a photo, which Telegram’s servers download from your public address. If they cannot reach it (Aperture only on the LAN, or APERTURE_PUBLIC_URL not set to a public HTTPS address), Telegram rejects the message. Make the address reachable, or use a channel that does not need the picture fetched from outside.
  • Pictures are missing in ntfy or email. The phone or mail client loads the picture from APERTURE_PUBLIC_URL. Check that the address works from where you read the message. Links expire after 24 hours.
  • Email fails to send. Use port 587 with STARTTLS. Some providers need an app password instead of your account password.
  • Too many alerts. Raise the rule’s cooldown, add an object filter, or tune motion detection.

Related: Automations · Object recognition · Mobile · Reverse proxy