Files
StarPunk/docs/decisions/ADR-074-notifications.md
T
2026-11-10 14:25:57 -07:00

6.9 KiB
Raw Blame History

ADR-074: Notifications through Apprise

Status

Accepted (v2.14.0, 2026-11-10)

Context

Responses now reach a note from two places: received webmentions (ADR-063) and backfeed from the crossposts (ADR-073). The owner only finds out about them by opening the site or the admin. Crossposts that finally fail, and silos that refuse a backfeed credential, are just as invisible.

Owners use different notification services. The production site uses Gotify (read on iOS through iGotify). Others use ntfy, Pushover, email, Matrix, Discord and so on. Apprise covers about 100 of them behind one URL syntax (gotifys://host/token, ntfys://topic, mailtos://…), both as a Python library and as a separate HTTP server (apprise-api).

Options considered:

  1. Gotify only. Simplest for this site, no use to anyone else.
  2. Post to an apprise-api server. Standard, but every owner needs one running, and messages take an extra hop.
  3. Embed the Apprise library. Sends straight to each service; an owner who prefers a central apprise-api can still use its apprise:// / apprises:// URL.
  4. Gotify plus a generic JSON webhook, hand-written. No dependency, but every other service needs glue the owner has to write.

Decision

1. Embed Apprise

StarPunk depends on the apprise package and sends with it directly. NOTIFY_URLS holds one or more Apprise URLs (space- or comma-separated); each message goes to all of them. With no URLs, notifications are off and nothing else changes.

2. What can be notified

NOTIFY_EVENTS is a comma-separated list. Default: reply,mention,quote,problems.

Event Sent when
reply, mention, quote, like, repost, bookmark a response of that type is first shown on a note, or first awaits moderation (received webmention or backfeed alike)
problems a crosspost fails for good (permanent error or last attempt), or a silo refuses the backfeed credential (ADR-073 Decision 9)

3. Messages

Markdown, so services that render it (Gotify, iGotify, ntfy, Matrix…) show links; others get the text.

  • Replies, mentions, quotes: one message each. Title "↩ Reply from Ana Lima via Bluesky" (or "💬 Mention from …", "❝ Quote from …"); body the response text (plain, up to 300 characters), then a link to the note's responses (<permalink>#responses).
  • Likes, reposts, bookmarks: grouped per note and type in each pass: "♥ 3 new likes on 'Starpunk now supports…'", with up to five names and a link to the note.
  • Awaiting moderation: when WEBMENTION_AUTO_APPROVE is off, the title says so and the link goes to the admin webmention page instead.
  • Problems: "⚠ Crosspost to Bluesky failed" / "⚠ Backfeed for Threads stopped" with the error and a link to the note's edit page or the Webmentions page.

Apprise's Gotify plugin has no click-through link, so the link is in the text.

3a. Priority

Every message is sent with the same priority, NOTIFY_PRIORITY (default normal). Apprise takes priority as a priority argument in each service URL, with values that differ by service, so StarPunk adds priority=<NOTIFY_PRIORITY> to each URL in NOTIFY_URLS that doesn't set one itself; a URL can still set its own. Apprise's names (low, moderate, normal, high, emergency) work for most services; Gotify also takes 0–10 (it maps the names to 0, 3, 5, 8, 10). Different priorities per event can come later.

4. Delivery

  • New column webmentions.notified_at. A sweep finds responses with notified_at IS NULL, validation_status = 'valid', a moderation status of approved or pending, and a type in NOTIFY_EVENTS, sends them, and sets notified_at. Types not selected are marked without sending.
  • The sweep runs in the webmention worker loop, which already runs in one process at a time (its file lock), so nothing is sent twice by several gunicorn workers. It handles received and backfed responses alike.
  • A failed send leaves notified_at empty, so the next pass (about 10 seconds later) retries, with backoff up to 15 minutes. Responses older than 24 hours that still haven't gone out are marked and dropped, with a warning, so an outage doesn't end in a flood. The last error is shown on the admin Webmentions page.
  • Problems are sent at the moment they happen (from the syndication and backfeed workers) and not retried: they are also in the log and admin.
  • Sending never blocks or breaks validation, crossposting or backfeed.

5. No floods from history

  • Migration 021 sets notified_at on every existing response.
  • Responses stored by a backfill check (ADR-073 Decision 8) are stored with notified_at set.
  • So are responses found on a crosspost's first check when its note is more than a day old (copies linked after the fact).
  • Grouping (Decision 3) keeps a busy note to one like message per pass.

6. Admin

  • Send test notification on the admin Webmentions page sends a test message to every URL and reports each result.
  • The page shows whether notifications are on, which events are selected, and the last send error.

7. Configuration

Setting Default Meaning
NOTIFY_URLS empty (off) Apprise URLs, space- or comma-separated
NOTIFY_EVENTS reply,mention,quote,problems which events are sent
NOTIFY_PRIORITY normal priority of every message, added to URLs that don't set one

Settings stay in the environment, like the rest of StarPunk's (ADR-052). URLs contain tokens and belong with the other secrets.

Consequences

  • One new dependency, apprise, with its own (requests, PyYAML, click, Markdown, certifi). It must install on Python 3.14 in the container image; this is checked before the release.
  • Owners can send to almost any service without writing glue, directly or through apprise-api.
  • Each response is notified at most once, a few seconds after it appears, and only if its type is selected.
  • Apprise opens outbound connections to whatever URLs the owner configures, outside the SSRF-safe fetcher. That is intended: the owner chooses these URLs, as with the crosspost targets. A service behind the same reverse proxy as StarPunk may need the deployment's internal-address entry (extra_hosts), as GoToSocial does.
  • Notification text includes other people's names and words, sent to the owner's own services only.

Alternatives considered

  • Gotify only / hand-written webhook. See Context, options 1 and 4: no dependency, but each service beyond Gotify needs glue the owner writes.
  • apprise-api only. See option 2. Still possible through an apprises:// URL.
  • Sending from where responses are stored (webmention worker, backfeed) instead of a sweep. Two code paths, no retry, and backfeed runs in every gunicorn worker. Rejected.
  • Choosing events in the admin UI. Possible later; the environment is where StarPunk's settings live today.