Pular para o conteúdo

Relay

Aponte os webhooks dos seus serviços para relay.pushward.app e receba notificações push sem Docker, self-hosting ou configuração por usuário.

Supported Providers

Grafana

POST /grafana
notification

Eventos

  • Firing
  • Resolved (grouped by alertname)
Demonstração da Atividade ao Vivo
No Android, as atividades deste provedor aparecem como Atualizações ao Vivo e as notificações dele como notificações do Android, na aba de notificações.

Public Relay

PushWard hosts a public relay at relay.pushward.app — no deployment required. Just point your services at it with your integration key. It supports every provider listed above; if you prefer to self-host, see the self-hosted setup further down.

Exemplo: webhook do Grafana
# Grafana Contact Point URL:
https://relay.pushward.app/grafana

# HTTP Header:
Authorization: Bearer hlk_YOUR_INTEGRATION_KEY

One URL for any service

You can also post any webhook to the relay root, https://relay.pushward.app/. Payloads from the providers above are recognised and handled exactly as on their own route, except TrueNAS and Gitea or Forgejo events other than Actions runs, which need their own route. Anything else goes to the universal webhook, which maps the payloads of dozens of known services through presets (some open an alert or progress card) and sends any other JSON as one plain notification. Where a service lets you set the path, its own route is still the better choice.

How It Works

  1. Receive — external services send webhooks to provider-specific routes
  2. Authenticate — the integration key is extracted from the Authorization: Bearer hlk_... header (or Basic Auth password for Radarr/Sonarr/Prowlarr/Bazarr/Komodo, or GenieKey for TrueNAS)
  3. Transform — the provider handler maps the webhook payload to a push notification or Live Activity update depending on the event type
  4. Forward — the request is sent to PushWard using the caller's integration key

Per-user usage is bounded by your account's plan (free tier monthly quotas; unlimited on paid).

Push Notifications vs Live Activities

Each provider delivers events as either a push notification (banner alert) or a Live Activity (Dynamic Island + Lock Screen), depending on the event type:

DeliveryProvidersUse case
Notification onlyGrafana, Prowlarr, BazarrOne-shot alerts — firing/resolved, health, grabs, subtitle downloads
Live Activity onlyArgoCD, Uptime Kuma, Backrest, Proxmox, Overseerr, Gatus, Changedetection, Paperless, Unmanic, Gitea, ForgejoMulti-step progress tracking (syncs, downloads, backups)
BothRadarr, Sonarr, Jellyfin, Komodo, TrueNASRadarr/Sonarr: Grab/Download → Live Activity; Health/Rename/Add/Delete → notification. Jellyfin: playback → Live Activity; library adds, scheduled tasks, auth failures → notification. Komodo: resolvable server conditions (CPU, memory, disk, unreachable, version mismatch, swarm) → Live Activity plus a companion notification; container state, build failed, image update → notification only. TrueNAS: each alert → Live Activity plus a companion notification
ℹ Informação

Relay requires PostgreSQL for persistent state (sync tracking, download lifecycle, playback progress across restarts and tenants). Stateless providers (Bazarr, Changedetection, Unmanic) still require a database connection to start.

Chega na versão 1.17.0 do app

Esta seção descreve um recurso de uma atualização do app que está em análise na App Store. Ele é desbloqueado aqui automaticamente assim que a atualização for lançada.

Chega na versão 1.7.0 do app

Esta seção descreve um recurso de uma atualização do app que está em análise na App Store. Ele é desbloqueado aqui automaticamente assim que a atualização for lançada.

Per-request overrides

Append query parameters to any provider webhook URL to override that provider's delivery behavior for a single request. An explicit parameter always wins over the provider-computed value and your static config; omitting a parameter leaves today's behavior unchanged.

ParameterValuesEffect
channelsComma-separated: activity, notificationRestricts which delivery surfaces this request may use. channels=notification suppresses Live Activities and only sends push notifications; channels=activity does the reverse. Must list at least one valid surface.
priorityInteger 0-10Sets the eviction / relevance priority for any Live Activity the request creates.
levelpassive or 0, active or 1, time-sensitive or 2, critical or 3Sets the notification interruption level for any push notification the request sends.
Chega na versão 1.17.0 do app
retract1 or 01 takes a resolved alert's push back off the devices instead of sending "Resolved" over it. See Retracted alerts.
Force a Grafana alert to a time-sensitive notification only
https://relay.pushward.app/grafana?channels=notification&level=time-sensitive
⚠ Aviso

An invalid value is rejected with 400 before the webhook is processed — an unknown channels surface, a priority that isn't an integer 0-10, or a level that isn't one of the names or numbers above. Fix the URL rather than retrying.

Chega na versão 1.17.0 do app

Esta seção descreve um recurso de uma atualização do app que está em análise na App Store. Ele é desbloqueado aqui automaticamente assim que a atualização for lançada.

Retracted alerts

A resolve normally sends a quiet "Resolved" push under the alert's collapse id. It replaces the alert on the Lock Screen and then stays there until someone clears it. With retract=1 the relay takes the alert's push back off the devices instead and sends no "Resolved". It does that only where the alert's push may still be up: an alert the relay still tracks, a push it recorded sending, or an event that only follows one, such as a restored health check or a resolved issue.

Take Gatus alerts back when they resolve
https://relay.pushward.app/gatus?retract=1
ProviderTaken backOn
GrafanaThe alert name's pushNothing left firing under the alert name (before 0.19.1: in the group)
Uptime Kuma, Gatus, KomodoThe monitor's, endpoint's or condition's pushUP, RESOLVED, resolved
TrueNASThe alert's pushThe clear, on /truenas/retract (below)
Universal webhookAn alert card's push, when the preset keys it on a correlation valueThe card ending
Radarr, Sonarr, ProwlarrThat health check's pushHealthRestored
Radarr, SonarrA download's manual-interaction pushThe import (Download) of the same download
Overseerr / SeerrThe issue report or reopenISSUE_RESOLVED
BackrestA failure pushThe next success of the same plan, repo and operation
  • It is best effort. The retract reaches PushWard on iPhone, iPad and Mac from 1.20 and on Android from 1.1.0, but never an Apple Watch or an app that was force-quit. When it fails, times out (5 seconds) or reaches no device, the relay sends the "Resolved" as it would without retract=1, so the alert is still replaced. Otherwise it sends only the retract, which is a delayed silent push and would take a "Resolved" sent after it down with the alert. Both go out only when the server took the retract but its answer did not arrive within the 5 seconds: the relay cannot tell that from a failure and sends the "Resolved", which the retract may then take down too.
  • For the same reason a retract can take down a new alert. A locked iPhone or a dozing Android phone can hold a silent push back for a while, so when an alert resolves and fires again before the retract has landed, as a flapping monitor does, the new alert's push goes with the old one and its inbox entry is marked read. Leave retract off for checks that flap.
  • A retract reaches the whole account (with an organization key scoped by groups or tags, every device of its audience), not only the key that sent the alert: every notification under that collapse id goes, whichever key or app sent it. Several ids are built from names or numbers that two instances of one service can share: Grafana's alert name, Uptime Kuma's monitor id, Gatus's endpoint group and name, the health check type for Radarr, Sonarr and Prowlarr, and Backrest's plan and repo. Two Uptime Kuma servers that both have monitor 1, or a radarr and a radarr-4k posting to one account, share those ids, and a resolve on one takes back the other's alert too. Give each such instance its own account, or leave retract off for them.
  • PushWard allows 10 retracts a minute per account, counted across all of its keys and shared with the CLI, the MCP server, Home Assistant and the Grafana plugin.
  • With ack=1 as well, the resolve still stops the repeats first.
  • A retract other than 1 or 0 is a 400.
  • A self-hosted relay needs version 0.19.0 or later for retract, /truenas/retract and the collapse ids below, and 0.19.1 for the Grafana groups and the Backrest retries and new ids described below. The hosted relay at relay.pushward.app is updated to each release.

Grafana has one collapse id per alert name, and a notification policy that groups by more than the alert name (by instance, or the default grafana_folder, alertname with two rules of one name in two folders) splits a name into groups whose pushes replace each other on the device. From relay 0.19.1, with retract=1 the relay records what each group reported firing, and a group takes the push back only when it resolves and no other group of the name is recorded firing. Whenever that is not sure, the group sends its "Resolved", as it would without retract=1: when another group still fires, when two groups resolve at the same moment, and for a name the relay already tracked before 0.19.1 or without retract=1, until that older record expires 24 hours after its last change. A group's record also lasts 24 hours from its last webhook, so keep the policy's repeat interval below that (Grafana's default is 4 hours). Relay 0.19.0 takes the push back as soon as one group has nothing left firing, which also takes down the alert of a group that still fires. To have each alert name's push taken back as soon as it clears, group its policy by alertname alone.

Radarr, Sonarr and Prowlarr give each health check type its own collapse id, <app>-health-<type> (radarr-health-indexerstatuscheck), so fixing one issue does not hide another that is still live, and HealthRestored replaces only its own issue's alert. A ManualInteractionRequired push gets one id per download, so a second title does not replace the first. The relay sends Overseerr's ISSUE_RESOLVED and ISSUE_REOPENED under the collapse id of their issue's report, keyed by issue_id (or by the title when the payload has none), so the latest of them replaces the others and another issue on the same title stays up.

The relay sends no push for a Backrest success under the default channels, so a failure push would stay up after the next good run. With retract=1 on the hook that delivers failures, the relay records the failure push for 7 days. Snapshot, prune, check and forget on one plan and repo push under one collapse id, so the record keeps the operation whose failure is showing. The next success of that operation takes it back, whatever URL the success arrives on; a success of another operation leaves it up. The plan and repo's any-error alert has an id of its own, and a success of any operation takes it back, so a check that passes also clears an any-error alert raised by a failed snapshot. Under channels=notification a success push goes out under the plan and repo's id and replaces whichever operation's failure shows there, which is then not retracted and no longer recorded; the any-error alert still is retracted. From relay 0.19.1 a retract that fails or reaches no device keeps the record, and the next success tries again; 0.19.0 tries once. Also from 0.19.1, once a retract has reached a device, the plan and repo's later pushes move to a new collapse id (backrest-<hash>-1, then -2, and the same for the any-error alert), so a failure right after the success, such as a forget that runs after the backup, cannot be taken down by the retract still on its way. A retract the server took but whose answer did not arrive within the 5 seconds counts as one that failed: the id stays, and a failure right after it can still be taken down. On a device the retract did not reach (an Apple Watch, an app before 1.20) the old push stays next to the new one.

A Radarr or Sonarr manual-interaction push sent with retract=1 is recorded the same way, and the import of that download takes it back. There is only one try: when that retract fails or reaches no device, the push stays up.

TrueNAS takes it from its own path, like ack. Set the API URL of its OpsGenie alert service to the URL below and the clear takes the alert's push back instead of sending "Resolved". There is no path that turns on both ack and retract.

TrueNAS API URL with retract on
https://relay.pushward.app/truenas/retract

Setup

1. Get Your Integration Key

Use sua chave de integração padrão no app PushWard em Configurações → Chave de Integração ou crie uma chave com escopo restrito para esta integração.

2. Self-Hosted (Optional)

If you prefer to run your own relay instance:

docker-compose.yml
services:
  pushward-relay:
    image: ghcr.io/mac-lucky/pushward-relay:latest
    ports:
      - "8090:8090"
    environment:
      PUSHWARD_URL: https://api.pushward.app
      PUSHWARD_DATABASE_DSN: postgres://user:pass@db:5432/relay?sslmode=disable
    restart: unless-stopped

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: relay
    volumes:
      - relay-data:/var/lib/postgresql/data

volumes:
  relay-data:

Authentication

Three patterns depending on the provider:

MethodProvidersFormat
Bearer tokenMost providersAuthorization: Bearer hlk_...
Basic AuthRadarr, Sonarr, Prowlarr, Bazarr, Komodo (their webhook settings only support Basic Auth)hlk_... as password, username ignored
GenieKeyTrueNASAuthorization: GenieKey hlk_...

Configuration

Variável de AmbienteDescriçãoPadrão
PUSHWARD_URLPushWard server URL--
PUSHWARD_DATABASE_DSNPostgreSQL connection string--
PUSHWARD_SERVER_ADDRESSHTTP listen address:8090

Each provider can be individually enabled/disabled and configured with its own priority, cleanup delay, and stale timeout via environment variables or YAML config.