Overpush

Overpush

<img src="https://xn--gckvb8fzb.com/images/chatroom.png" width="275">

Overpush is a self-hosted, drop-in replacement for Pushover that can use XMPP, as well as a wide variety of other services (see below) as the delivery method while maintaining full compatibility with the Pushover API and also offering a flexible HTTP webhooks endpoint. This allows existing setups to continue functioning with minimal changes, while allowing more complex setups further down the road.

Think of Overpush as a bridge between HTTP requests (webhooks) and various target services, such as XMPP, Matrix, Signal, and others:

                    ┌────────────────┐                    
                    │                │                    
                    │  HTTP REQUEST  │                    
                    │                │                    
                    └────────┬───────┘                    
                             │                            
                             │                            
                             │                            
                    ┌────────▼───────┐                    
                    │                │                    
                    │  OVERPUSH API  │                    
                    │                │                    
                    │────────────────│                    
                    │     REDIS      │                    
                    │────────────────│                    
                    │                │                    
                    │     WORKER     │                    
                    │                │                    
                    └────────┬───────┘                    
                             │                            
        ┌────────────────────┼──────────────────┐         
        │                    │                  │         
┌───────▼────────┐  ┌────────▼───────┐  ┌───────▼────────┐
│                │  │                │  │                │
│     SIGNAL     │  │      XMPP      │  │     MATRIX     │
│                │  │                │  │                │
└────────────────┘  └────────────────┘  └────────────────┘

The Overpush API accepts HTTP POST requests in multiple formats, including:

• application/x-www-form-urlencoded
• multipart/form-data
• application/json
• application/xml/text/xml

The configuration file allows you to define custom templates using Go's text/template syntax to extract and transform data from webhook payloads.

Internally, Overpush uses asynq to queue messages for processing by a background worker. This requires a Redis-compatible server as a backend. You can run your own instance (e.g. Redis, Valkey, KeyDB, DragonflyDB) or use the free Essentials plan from Redis Cloud, which is reliable and sufficient for most use cases.

The Overpush worker has native support for XMPP as a target. For other services, it integrates with Apprise, requiring the apprise CLI tool to be available on the same host.

Build

To build Overpush, simply clone this repository and run the following command inside your local copy:

$ go build

Configure

The Overpush configuration is organized into four main sections:

• [Server]: Specifies server settings, like the IP address and port on which Overpush should run.
• [Redis]: Configures the connection to a Redis server or cluster.
• [Users]: Defines individual users and their settings.
• [Targets]: Sets up message targets (or destinations) for each user.

Overpush will try to read the overpush.toml file from one of the following paths:

• /etc/overpush.toml
• $XDG_CONFIG_HOME/overpush.toml
• $HOME/.config/overpush.toml
• $HOME/overpush.toml
• $PWD/overpush.toml

Every configuration key available in the example overpush.toml can be exported as environment variable, by separating scopes using _ and prepend OVERPUSH to it.

Sources

The Overpush API accepts requests to the legacy /1/messages.json endpoint used by Pushover, which allows you to simply flip the host/domain in your configurations to drop in Overpush instead of Pushover. In addition, Overpush offers a flexible HTTP POST endpoint on /:token (where :token is an Application's Token), which can be used to retrieve various different webhook formats.

Pushover clients

The official Pushover API documentation shows how to submit a message to the /1/messages.json endpoint. Replacing Pushover with Overpush only requires your tooling to support changing the endpoint URL to your own server. Enable = true

You can find an example script here that serves as a command-line API client for both Pushover and Overpush to submit notifications. Since Overpush does not yet offer 100% feature parity with Pushover, some features are not available.

Custom HTTP Webhooks

Overpush can handle a wide variety of custom webhooks by configuring dedicated Applications in its config. Here are some examples:

CrowdSec

Add the following application to your Overpush config:

[[Users.Applications]]
Enable = true
Token = "XXX"
Name = "CrowdSec"
IconPath = ""
Target = "your_target"
TargetArgs.Destination = "you@your-xmpp-server.im"
Format = "custom"
CustomFormat.Message = '{{ webhook "body.alerts.0.message" }}'
CustomFormat.Title = 'CrowdSec: {{ webhook "body.alerts.0.scenario" }}'

Edit the CrowdSec config notifications/http.yaml (under /etc/crowdsec/notifications/http.yaml or /usr/local/etc/crowdsec/notifications/http.yaml) as follows:

type: http
name: http_default

log_level: info

format: |
  {"alerts":{{.|toJson}}}

url: https://my.overpush.net/XXX

method: POST

headers:
  Content-Type: application/json

# skip_tls_verification:  true

Set XXX to the unique token of the Overpush application.

Grafana

Add the following application to your Overpush config:

[[Users.Applications]]
Enable = true
Token = "XXX"
Name = "Grafana"
IconPath = ""
Target = "your_target"
TargetArgs.Destination = "you@your-xmpp-server.im"
Format = "custom"
CustomFormat.Message = '{{ webhook "body.message" }}'
CustomFormat.Title = '{{ webhook "body.title" }}'
CustomFormat.URL = '{{ webhook "body.externalURL" }}'

Create a new contact point in your Grafana under /alerting/notifications/receivers/new, choose the Webhook integration add set your Overpush instance:

https://my.overpush.net/XXX

Set XXX to the unique token of the Overpush application.

Targets

Targets are the target services that messages should be routed to. Overpush supports XMPP out of the box, but can use Apprise to forward messages to a wide range of different services.

Each Application must specify a Target. Multiple Application configurations might use the same target.

XMPP (built-in)

Overpush supports XMPP (without OTR/OMEMO) out of the box, without any additional software. The configuration for the XMPP target might look like this:

[[Targets]]
Enable = true
ID = "your_target"
Type = "xmpp"

  [Targets.Args]
  server = "conversations.im"
  tls = "true"
  username = "my_bot@conversations.im"
  password = "hunter2"

To use this target, specify its ID inside an Application configuration:

...
Target = "your_target"
TargetArgs.Destination = "you@your-xmpp-server.im"
...

Apprise

Overpush supports the following platforms via Apprise:

• AWS SES
• Bark
• BlueSky
• Chanify
• Discord
• Emby
• Enigma2
• FCM
• Feishu
• Flock
• Google Chat
• Gotify
• Growl
• Guilded
• Home Assistant
• IFTTT
• Join
• KODI
• Kumulos
• LaMetric Time
• Line
• LunaSea
• Mailgun
• Mastodon
• Matrix
• Mattermost
• Microsoft Power Automate / Workflows (MSTeams)
• Microsoft Teams
• Misskey
• MQTT
• [Nextcloud](https://github.com/car