push_outputs: is a new sink a channel, a template, or a library?

[IsmaelMartinez]

A small decision, and it is holding up a contributor's pull request rather than a roadmap item.

push_outputs has four channels today: stdout, file, webhook and slack. webhook is generic, a JSON POST to a URL you configure. slack is the only vendor-shaped one, in that it knows the payload that service wants.

Telegram has now been offered twice as a fifth. I asked #3098 to drop it so we could settle this first, and #3167 has since implemented it independently and cleanly, so the question is due. Three ways to answer it.

A, keep adding vendor channels. About thirty lines and two settings keys each, off by default. Cheap on its own. The cost is that each one is permanent, we own its payload when the vendor changes it, and Discord, Teams and Mattermost all have the same claim the moment we say yes once.

B, a body template over webhook. Telegram becomes configuration rather than code. The cost moves to the operator, who now writes the template, and a bad one fails at runtime instead of in review.

C, hand it to a library. Apprise exists for exactly this. One apprise channel taking a list of URLs, and tgram://bottoken/chatid is the whole Telegram feature. What I measured rather than assumed:

• 1.13.1, BSD-2-Clause, released a week ago, 74 releases.
• 150 plugin modules plus 6 subpackages. Telegram, Slack, Discord, Mattermost, Webex, Rocket.Chat, ntfy, Pushover, Matrix, email, and custom_json for anything else.
• Resolving it against our own pyproject adds two packages, apprise and markdown. requests, requests-oauthlib, click, PyYAML 6.0.1 and certifi 2024.8.30 are already there and unchanged.
• The integration is 11 lines. I spiked it: one if "apprise" in channels: block in push_outputs, the same shape as the existing four, plus two config keys. It delivered to a local sink with the title and markdown body intact on the first run. The import apprise sits inside the function, so operators who do not use it pay nothing.
• It has async_notify and a concurrent dispatch path, so it is better than the blocking requests.post we use now.
• Credentials live in the URL, and push_outputs is already host-only with an empty allowlist for the SSRF and exfiltration reasons in config_security.py:14-17, so they are already in the right place.

C is unlike B in that the operator does not write a payload; the library owns each service's format. It is unlike A in that we never write another vendor channel.

On whether it is too bulky, since that was the first question asked of it. 1.7MB wheel, 5.3MB unpacked, of which 3.5MB is the 150 plugins and 744K is desktop-notification assets we would never touch. Dependencies are genuinely modular: the base install needs nothing per service, because Telegram, Slack, Discord, Teams and Mattermost are all plain HTTP through requests, and only the exotic ones (MQTT, XMPP, Growl, PGP, SMPP) sit behind an all-plugins extra we would not install. The code is not modular: all 150 ship regardless. Importing a single plugin directly costs 130ms instead of the full scan, but then we need a name-to-class map and we are writing vendor code again, which defeats the point.

The honest costs of C. It is a new runtime dependency for a feature, and AGENTS.md says to ask before adding one, which is part of why I am asking. We inherit its cadence and its security surface, and we would be shipping 150 plugins to use one. The first send in a process triggers a one-time plugin scan of about 1.2 seconds, invisible in a webhook service but real in a short CLI run. It makes slack and webhook redundant, so we either deprecate them and break existing config or carry both. And operators parsing the current webhook JSON would lose that exact shape.

I lean C, with slack and webhook kept as they are and no deprecation, so nothing existing breaks. Second choice A for Telegram alone, since #3167 already works.

@naorpeled @DanaFineTLV @ofir-frd, and @dwin-gharibi @noooooooookro since you both wrote this.

Unlike #3147 this is not necessary post-v1 work. It is one channel, not a runtime, so a quick answer unblocks someone.

[IsmaelMartinez]

Answering my own question: I would pick C, the library.

Four hand-written channels, plus the ones that keep arriving on the sidelines and stalling (#3167, and #3097 which closed as not planned), is the argument for it rather than against. Adopting a library lets us delete most of the per-channel code instead of adding a fifth copy of it, and turns the next sink into configuration rather than a review cycle. I would rather simplify what is already here and bring the sidelined work back through that path than keep growing the current shape.

The one thing whoever picks this up must carry is _push_outputs_sink_url. It is this section's only boundary check, and tgram:// or discord:// are not https by construction, so the scheme check and allow_redirects=False cannot simply move inside the dependency. Keep an equivalent check at our boundary.

Leaving this open for that work.

[erezlev13]

Hi @IsmaelMartinez, I’m happy to pick this up. I’ll look further into Apprise and the alternatives, particularly how to preserve the existing security checks and compatibility. I’ll share my findings and proposed approach here before moving ahead with implementation.

[erezlev13]

Hi @IsmaelMartinez, I’ve investigated the current implementation and tested Apprise 1.13.1 with intercepted HTTP transport.

My preference for the current scope is a small native-adapter design using strategy and factory patterns. Each destination owns its payload and provider-specific behavior, while dispatch, failure isolation, and shared HTTP policy stay separate. This keeps the integrations explicit and avoids adding a runtime dependency before we have a concrete need for broader provider coverage.

I recognize that this doesn’t eliminate the maintenance cost you raised: we would still own each provider’s API changes. I think that tradeoff is reasonable for a small, deliberately supported set of destinations.

I opened [Draft PR #3854](#3854) to make the proposed structure concrete. It extracts the four existing sinks behind an OutputSink interface and a small factory registry, preserving their configuration, payloads, delivery order, and security checks. It adds no provider or dependency. The targeted tests and documentation checks pass.

Apprise remains a credible alternative, and its benefits go beyond making providers easy to add: it maintains provider-specific authentication, payload formatting, message splitting, and some retry/throttling mechanisms. Used as an embedded library, it also requires no additional running service. Credential storage, provisioning, rotation, and access control would still remain our responsibility.

The main integration considerations I found are:

• Transport policy: the tested Telegram path uses HTTPS and verifies certificates by default, but follows redirects. URL options can disable certificate verification and override the asset-level redirect default. We need to enforce our policy rather than rely on those defaults.
• Logging: the Telegram debug path included the synthetic token and message payload. We need to ensure library diagnostics cannot expose credentials or review content.
• Delivery policy: configurable retries exist, but the tested configuration retried HTTP 400 responses, while a default HTTP 429 received no retry. We still need to define retryable failures, rate-limit handling, delivery time limits, and duplicate-delivery behavior.
• Dependency maintenance: we would need to review upgrades and keep regression tests against the real library’s parsing and delivery paths.

If Apprise is still your preferred direction, I’m comfortable taking that route. We would need to define the supported destination scope, enforce the equivalent of our current boundary checks, control logging, and preserve compatibility—especially the generic webhook JSON contract. I’d also clarify whether the intended scope is an additional Apprise channel or a compatible migration of existing integrations.

Separately, I suggest a focused follow-up ticket for bounded retries/backoff, rate limits, idempotency and duplicate delivery, and whether non-blocking dispatch or a durable queue is warranted. These decisions apply to either approach. Failure isolation and response-status handling were already addressed in #3306/#3307, and async delivery has prior work in #3741, which I saw you parked pending this decision. I didn’t find a dedicated ticket covering the remaining delivery-policy questions.

[IsmaelMartinez]

Thanks @erezlev13, careful work, and #3854 is a clean shape. I'm fine with native adapters for now, provided the sink interface stays the path to a library later, so an Apprise sink can replace them one by one instead of the set growing for ever. The destinations I care about are Microsoft Teams, Discord and EventBridge alongside today's Slack. Telegram (#3098, #3167, from #3097) and WhatsApp are welcome community additions; @noooooooookro, #3167 rebased onto OutputSink would be a good first one.

[erezlev13]

Thanks @IsmaelMartinez, that direction works for me. I’ve marked [#3854](#3854) ready for review, and it’s now awaiting your review.

I agree that the sink interface should preserve a path to Apprise later, so individual native adapters can be replaced incrementally.

I’m also happy to take on the Microsoft Teams, Discord, and EventBridge integrations as follow-up contributions when needed, using this interface and keeping each addition in a focused PR.

[IsmaelMartinez]

Probably telegram is the more important one. MS Teams next and EventBridge. Discord can wait to see if the community ask for it. Thanks!!

[erezlev13]

Hi @noooooooookro, now that native adapters are the agreed direction, are you interested in adapting #3167 to the OutputSink interface in #3854? I’m happy to help with the adaptation and tests. If you’re unavailable, I’d be happy to coordinate continuing your existing implementation with you and @IsmaelMartinez.

[IsmaelMartinez]

both has been merged so closing this. Ideally we should add email, msteams, mqtt, sns and a few others, but we can do that once we got community interest. I would say that if we start needing to add functionality around the solution that is around deduplication, retries and we start to see a scope creep then we move to apprise (the library version). Thanks again!