Skip to content

ADR — H5: notifications through Apprise (T27)

Status: accepted, hypothesis H5 declared not run (2026-11-13). Scope: the notify node and the notification channels of T27 (src/extractit/nodes/notify/).

Hypothesis

H5: Apprise sends to Slack, Microsoft Teams (Power Automate flows) and SMTP well enough that ExtractIt needs no adapters of its own. The ticket asks for a real test send to Slack, Teams and an SMTP server, documented in the PR, or a one-day fallback to adapters of our own.

What was verified, and with what

Piece Verified against Not verified
Slack (hooks.slack.com webhook, or bot token + channel) A fake HTTP server that stands in for the host: the request path, the severity prefix, the values, the run link and the escaping of <!channel> / <@U…> A real workspace
Teams (Power Automate flow URL, *.logic.azure.com, *.webhook.office.com) The same fake server: path and query kept, [CRITICAL] subject, values A real flow; the schema of the card Teams renders
Email aiosmtpd on a local port: [CRITICAL] subject, HTML body with escaped values, up to 10 recipients STARTTLS/TLS against a real provider, authentication
Webhook channel A local receiver: JSON signed with Standard Webhooks, verified with standardwebhooks —

The user decided on 2026-11-10 that no real account is used (no Slack workspace, Teams tenant or external SMTP) until the product has them. So the real test send of H5 was not run: nothing in this ADR claims it works against the real services.

Decision

Keep Apprise (BSD-2-Clause, pinned >=1.9,<2 in the core and in ee/) behind a narrow seam: channels.apprise_url(kind, config) builds the URL from validated fields and channels.send_apprise(...) is the only function that touches the library. The webhook channel does not use Apprise: it goes through the SSRF-safe client of the deliveries.

  • The hosts of Slack and Teams are fixed by the Apprise plugin; the admin cannot point a channel at an arbitrary host. Email hosts are chosen by the administrator (an SMTP server is a trusted destination of the organization). This is why those three kinds go through Apprise and the rest does not (Apprise cannot pin the resolved IP).
  • Apprise does not expose HTTP status codes: a refused message is DeliveryError("the slack service did not accept the message"), retried three times as a durable step. No URL, token or password appears in the message or the logs.
  • Old Office 365 connector URLs are retired by Microsoft: only Power Automate flow hosts are accepted.

Fallback (if the real test fails)

If a real send fails in a way Apprise cannot be configured around, replace only send_apprise (about one day):

  1. Slack: POST the {"text": …} JSON to the validated webhook URL through net.post's SSRF-safe path (host allow-list hooks.slack.com).
  2. Teams: POST an Adaptive Card to the flow URL (host allow-list as above).
  3. Email: aiosmtplib with the same security modes.

Nothing else changes: validation, templates, limits, idempotency and the ledger sit above the seam.

How to close H5 when accounts exist

  1. Create a Slack incoming webhook, a Teams flow and an SMTP sandbox (Mailpit or the provider's).
  2. POST /v1/notification-channels for each and POST …/{id}:test with dry_run: false.
  3. Check the message arrived with the [TEST] [INFO] subject; write the result and the Apprise version here, and delete the "not run" markers of this ADR and of the T27 delivery note.

Consequences

  • The risk "the compatibility of async_notify and of the Teams URLs depends on the pinned version" stays open: the pinned version (1.13.1 at the time) sends synchronously inside a durable step (notify, in a worker thread), which does not depend on async_notify.
  • Notification delivery is at most the retries of the step (3); an outage longer than that fails the node (NOTIFY_FAILED) and the run ends partially_succeeded.