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 |
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):
- Slack:
POSTthe{"text": …}JSON to the validated webhook URL throughnet.post's SSRF-safe path (host allow-listhooks.slack.com). - Teams:
POSTan Adaptive Card to the flow URL (host allow-list as above). - Email:
aiosmtplibwith the samesecuritymodes.
Nothing else changes: validation, templates, limits, idempotency and the ledger sit above the seam.
How to close H5 when accounts exist
- Create a Slack incoming webhook, a Teams flow and an SMTP sandbox (Mailpit or the provider's).
POST /v1/notification-channelsfor each andPOST …/{id}:testwithdry_run: false.- 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_notifyand 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 onasync_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 endspartially_succeeded.