Self-Host Overpush for Grafana and CrowdSec with Localtonet

How Overpush fits into a webhook notification workflow

Overpush acts as a bridge between HTTP senders and notification delivery services. A monitoring or security system sends an HTTP POST request to Overpush. Overpush interprets the request using either its Pushover-compatible API or a custom application template, places the resulting work into a queue backed by a Redis-compatible server, and processes that work through a background worker.

The built-in delivery target is XMPP. Overpush can also integrate with Apprise when the apprise command-line tool is installed on the same host, which makes additional destination services available through Apprise. The target is distinct from the source application: Grafana and CrowdSec can each have their own application token and transformation template while both applications route to the same target.

Overpush exposes two relevant endpoint patterns. The legacy /1/messages.json endpoint is intended for software that already speaks the Pushover API and lets an operator replace the Pushover host with the Overpush host. The custom /:token endpoint is better suited to arbitrary webhook bodies from systems such as Grafana and CrowdSec.

Prepare the host and required services

This tutorial follows the source-build installation path documented by the Overpush project. The project repository contains a Dockerfile, but the supplied installation documentation specifically explains cloning the repository and running go build. It does not document a package-manager installation or a complete container deployment workflow, so this guide does not invent one.

Before building, prepare the following components:

• Git: required to clone the source repository.
• A Go toolchain: required by go build. Use a version compatible with the current repository's go.mod file. A fixed version is not stated here because it should not be guessed.
• A Redis-compatible server: Redis, Valkey, KeyDB, or DragonflyDB can provide the required backend. It may run locally or on another host reachable by Overpush.
• A delivery target: prepare an XMPP account and destination if using native XMPP, or install and configure Apprise if using one of its supported services.
• Grafana, CrowdSec, or another sender: this can be on the same network for initial testing or external once the public tunnel is ready.
• The Localtonet client: install it later on the machine that can reach the Overpush listener. The client establishes an outbound connection to our relay.

Confirm that Git and Go are available before cloning:

git --version
go version

Also verify that the Redis-compatible service is running and reachable using the administrative or health-check method documented for the backend you selected. Redis connection parameters vary by deployment, so copy the actual host, port, database, username, password, and TLS requirements from that deployment rather than assuming local defaults.

Clone and build Overpush from source

The supported installation evidence is concise: clone the repository and run go build inside the local copy. The following steps preserve that documented sequence.

git clone https://github.com/mrusme/overpush.git
cd overpush
go build

A successful command should complete without a compiler error. Locate the executable produced in the repository directory and record its exact name and path. The evidence used for this tutorial does not define the output filename as a cross-platform guarantee, so automation should inspect or explicitly control the build artifact rather than rely on an assumed name.

Building only confirms that the source compiles. It does not prove that Redis is reachable, the target credentials are valid, the templates match incoming webhook bodies, or the HTTP listener is available. Those checks happen after configuration and startup.

Configure the server, queue, applications, and targets

Overpush organizes its configuration into four main areas:

• [Server] defines the IP address and port on which the API listens.
• [Redis] defines the connection to a Redis server or cluster.
• [Users] defines users and their applications.
• [Targets] defines destinations to which applications route messages.

The project looks for overpush.toml in the following locations:

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

Use one intentional location so the startup environment is predictable. In particular, relying on $PWD/overpush.toml can produce different results when a service manager launches the process from a different working directory.

Configuration keys can also be exported as environment variables. The project describes the conversion as separating configuration scopes with underscores and prefixing the result with OVERPUSH. Consult the example overpush.toml from the exact revision you built before translating keys. This guide does not invent environment-variable names for fields that are not present in the supplied evidence.

Define the listener and Redis connection

Start from the example configuration included with the repository. Set the server IP address and port to values suitable for the host. For a service reached only by software on the same machine, a loopback listener is usually the smallest exposure surface. If the Localtonet client runs in another container, virtual machine, or physical device, the listener must instead be reachable from that client.

Configure the Redis section using the real parameters of your backend. Do not assume that an unauthenticated local connection is acceptable. Production deployments should follow the backend operator's authentication, network filtering, and TLS requirements.

Create a Grafana application

A Grafana webhook body can be transformed into a notification using its message, title, and externalURL fields. Add an application under the appropriate user in your complete Overpush configuration:

[[Users.Applications]]
Enable = true
Token = "REPLACE_WITH_UNIQUE_GRAFANA_TOKEN"
Name = "Grafana"
IconPath = ""
Target = "notification_target"
TargetArgs.Destination = "REPLACE_WITH_DESTINATION"
Format = "custom"
CustomFormat.Message = '{{ webhook "body.message" }}'
CustomFormat.Title = '{{ webhook "body.title" }}'
CustomFormat.URL = '{{ webhook "body.externalURL" }}'

The Target value must match the ID of an enabled target. The destination argument must be meaningful to that target. Use a separate application token for Grafana rather than sharing a token with CrowdSec.

Create a CrowdSec application

The documented CrowdSec example wraps alerts in an alerts array. Its Overpush template selects the first alert and extracts the message and scenario fields:

[[Users.Applications]]
Enable = true
Token = "REPLACE_WITH_UNIQUE_CROWDSEC_TOKEN"
Name = "CrowdSec"
IconPath = ""
Target = "notification_target"
TargetArgs.Destination = "REPLACE_WITH_DESTINATION"
Format = "custom"
CustomFormat.Message = '{{ webhook "body.alerts.0.message" }}'
CustomFormat.Title = 'CrowdSec: {{ webhook "body.alerts.0.scenario" }}'

This template expects a particular payload shape. If your CrowdSec event source produces another schema, inspect a safe sample payload and update the template accordingly. A valid JSON request can still result in an empty or unusable notification when the template references fields that are absent.

Define an XMPP target

XMPP is built into Overpush and does not require Apprise. A target follows this structure:

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

[Targets.Args]
server = "REPLACE_WITH_XMPP_SERVER"
tls = "true"
username = "REPLACE_WITH_XMPP_USERNAME"
password = "REPLACE_WITH_XMPP_PASSWORD"

The application Target values in the previous examples must equal notification_target. Replace every credential and destination placeholder. Overpush's documented native XMPP support does not include OTR or OMEMO, so do not describe it as providing those message-layer protections.

If you choose an Apprise-backed target instead, install the Apprise CLI on the same host and follow the Overpush example configuration for the specific target type. The available evidence confirms the integration requirement but does not provide enough target-specific configuration details to reproduce every Apprise service safely here.

Start Overpush without assuming an undocumented command

At this point you should have a compiled executable and a complete configuration derived from the repository's example. The available Overpush instructions do not document a canonical startup command, service unit, command-line flag set, daemon user, or default port. For that reason, a responsible tutorial should not present a guessed command as authoritative.

Locate the artifact created by go build, review its built-in help if it provides one, and launch it according to the behavior of the revision you built. Start it with a working directory and environment that allow it to find your selected configuration file. Keep its output visible during the first run so configuration parsing, Redis connection, target, and listener errors are not hidden.

For long-running operation, place the verified invocation under the service manager used by your operating system. Run it as a dedicated, unprivileged account where practical, grant that account read access only to the required configuration and executable, and configure intentional restart and log-retention behavior. Exact service-manager files are omitted because the executable path, startup syntax, account name, and host platform are deployment-specific and are not established by the project evidence supplied for this guide.

Verify the complete workflow locally

Test in layers. First confirm that the process stays running and listens on the configured address and port. Next submit a request to the custom endpoint. Finally verify that the worker processes the queued message and that the target receives it.

Test the Grafana-shaped payload

Send a JSON body directly to the Grafana application token:

curl -i \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"title":"Overpush local test","message":"Grafana-shaped webhook delivery is working","externalURL":"https://example.invalid/alert"}' \
  "http://OVERPUSH_HOST:OVERPUSH_PORT/REPLACE_WITH_UNIQUE_GRAFANA_TOKEN"

The .invalid domain is deliberately non-routable and is used only as harmless sample content. Replace it if you need to verify that your destination renders a real alert URL.

Test the CrowdSec-shaped payload

The CrowdSec template expects alerts[0].message and alerts[0].scenario:

curl -i \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"alerts":[{"message":"Local CrowdSec webhook test","scenario":"manual-test"}]}' \
  "http://OVERPUSH_HOST:OVERPUSH_PORT/REPLACE_WITH_UNIQUE_CROWDSEC_TOKEN"

Do not treat acceptance by the HTTP endpoint as the only success criterion. Because processing is queued, confirm all of the following:

• The HTTP connection reaches the Overpush listener.
• The application token selects the intended application.
• The request body parses in the expected format.
• The template extracts non-empty values.
• The Redis-compatible backend accepts the queued work.
• The worker processes the work.
• The selected XMPP or Apprise destination receives the notification.

The supplied Overpush material does not establish one universal success response body or status code for every endpoint and failure mode. Inspect the actual HTTP response, Overpush logs, backend health, and final destination rather than scripting around an assumed response.

Test the Pushover-compatible route when needed

Software that already supports Pushover can target /1/messages.json. Its request must follow the Pushover API shape supported by the Overpush version you installed. Overpush does not claim complete feature parity with Pushover, so test the particular fields and priority behavior your sender relies on before replacing an existing production endpoint.

Connect Grafana and CrowdSec to the verified endpoint

Configure a Grafana webhook contact point

In Grafana, create a contact point and choose the Webhook integration. The Overpush project identifies the contact-point creation location as /alerting/notifications/receivers/new. Set the destination to the custom application endpoint:

https://YOUR_PUBLIC_HOST/REPLACE_WITH_UNIQUE_GRAFANA_TOKEN

Use POST and send JSON matching the fields referenced by the Overpush template. Then use Grafana's available test function or trigger a controlled test alert. Confirm both receipt by Overpush and final delivery.

Grafana OnCall is a separate workflow from ordinary Grafana Alerting contact points. The documented Grafana OnCall OSS project is archived as of March 24, 2026, with active development continuing in Grafana Cloud IRM. If you still operate OnCall OSS, it supports outgoing webhooks and personal notification webhooks, but evaluate its archived status before making it a new long-term dependency.

For an OnCall outgoing webhook, configure the URL, POST method, optional headers, and body so the payload agrees with your Overpush application template. Avoid copying API examples containing placeholder authorization values into production. OnCall supports several trigger types, so choose only the events needed for your notification policy.

Configure the CrowdSec notification file

For the Overpush project's documented CrowdSec integration, edit the CrowdSec HTTP notification configuration at the path appropriate to your installation. The documented candidate locations are:

/etc/crowdsec/notifications/http.yaml
/usr/local/etc/crowdsec/notifications/http.yaml

Configure the notification to wrap the alert data in the alerts key expected by the Overpush template:

type: http
name: http_default
log_level: info
format: |
  {"alerts":{{.|toJson}}}
url: https://YOUR_PUBLIC_HOST/REPLACE_WITH_UNIQUE_CROWDSEC_TOKEN
method: POST
headers:
  Content-Type: application/json

Preserve CrowdSec's YAML indentation and replace the URL and token. Restart or reload CrowdSec using the method documented for your installation, then generate a safe test notification.

CrowdSec Console also offers a webhook integration that sends POST requests and can use a bearer-style header or Basic Authentication. Its retry behavior includes non-200 responses, DNS failures, connection timeouts, connection refusal, TLS handshake failures, and temporary endpoint unavailability, with up to five attempts and increasing waits. That Console workflow may produce a different payload from the local CrowdSec notification file shown above. Match the Overpush template to the actual Console event schema before enabling a production rule.

Expose the working Overpush API with Localtonet

Once local requests succeed, place the Localtonet client on the machine running Overpush or on another device that can reach its configured listener. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, a firewall change, VPN setup, or a public IP address.

Overpush is an HTTP service, so use an HTTP tunnel rather than a raw TCP tunnel for this workflow. The tunnel maps its public HTTPS address to the local IP address and port you selected in Overpush's [Server] configuration.

For current dashboard details, use the Localtonet documentation. The public hostname must be combined with the appropriate Overpush route:

https://YOUR_LOCALTONET_HOST/REPLACE_WITH_UNIQUE_GRAFANA_TOKEN
https://YOUR_LOCALTONET_HOST/REPLACE_WITH_UNIQUE_CROWDSEC_TOKEN
https://YOUR_LOCALTONET_HOST/1/messages.json

Secure and operate the deployment

An application token in a URL acts as a routing secret, but placing a secret in the path requires care. URLs may appear in sender configuration, reverse-proxy records, screenshots, browser history, monitoring systems, and application logs. Generate a different high-entropy token for each application, avoid human-readable values, redact request paths from shared diagnostics, and rotate a token if it is exposed.

Apply least privilege at each layer. The Overpush process needs access to its configuration, Redis backend, and selected target, but it should not require broad host permissions. The Redis-compatible backend should not be publicly reachable merely because Overpush is public. Likewise, an XMPP or Apprise credential should belong to a purpose-specific notification identity where the destination supports that model.

Publish only the endpoint needed by senders. Do not use a broader network exposure mechanism when an HTTP tunnel to one listener is sufficient. The Localtonet tunnel forwards traffic to the configured local target; it does not replace authentication, token rotation, payload validation, host patching, or application-level authorization.

Routine maintenance should include reviewing upstream Overpush releases, rebuilding in a controlled environment, backing up the configuration securely, testing Redis connectivity, and sending a synthetic notification. When changing a template, test both firing and recovery-style events if the sender emits different payloads for those states.

Stop the Localtonet tunnel during maintenance if Overpush should not receive external traffic. Remember that stopping a tunnel is different from deleting it. Creating or retaining a tunnel configuration also does not mean that it is currently running.

Troubleshoot the workflow layer by layer

The build fails

Confirm that you are in the repository root and that the Go version is compatible with the checked-out go.mod. Read the first compiler or module error rather than only the final failure line. If the failure began after updating the repository, return to the approved revision or investigate the dependency change before modifying source code.

Overpush cannot find its configuration

Verify the process account's home directory, XDG_CONFIG_HOME, current working directory, and access to the selected file. A configuration that loads in an interactive shell may not load under a service manager because the account, environment, or working directory changed.

The HTTP connection is refused

Confirm that Overpush is still running and that the test uses the exact configured IP and port. If the listener is bound only to loopback, a Localtonet client on another device cannot reach it. If the client is on the same machine, a loopback target may be appropriate. Check host networking tools for the actual listener rather than assuming a default port.

The request is accepted but no notification arrives

Trace the path in order: application token, payload parser, template fields, queue insertion, worker processing, target selection, destination credentials, and outbound network access. Confirm that the application's Target exactly matches an enabled target ID. For Apprise-backed delivery, confirm the CLI is installed on the same host and executable by the Overpush process account.

The notification contains empty fields

Capture a sanitized example payload and compare its structure with the template. The Grafana example expects body.message, body.title, and body.externalURL. The CrowdSec example expects an alerts array with message and scenario in its first element. A change in the sender's body or wrapping structure requires a corresponding template change.

Local tests work but the public URL fails

Verify that the Localtonet client is connected, the HTTP tunnel is running, and its local target matches the tested Overpush address and port. Test the public URL with the same body that worked locally. Also confirm that the sender uses HTTPS, the correct hostname, and the correct application token path.

Grafana or CrowdSec retries repeatedly

Inspect the status and body returned by the public endpoint, then correlate the request time with Overpush and Localtonet availability. For CrowdSec Console webhooks, non-200 responses, DNS failures, connection timeouts, refused connections, TLS failures, and temporary endpoint unavailability can cause retries. Repair the underlying endpoint instead of disabling TLS verification.

Frequently asked questions