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
/grafanaEventos
- Firing
- Resolved (grouped by alertname)

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.
# Grafana Contact Point URL:
https://relay.pushward.app/grafana
# HTTP Header:
Authorization: Bearer hlk_YOUR_INTEGRATION_KEYOne 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
- Receive — external services send webhooks to provider-specific routes
- 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) - Transform — the provider handler maps the webhook payload to a push notification or Live Activity update depending on the event type
- 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:
| Delivery | Providers | Use case |
|---|---|---|
| Notification only | Grafana, Prowlarr, Bazarr | One-shot alerts — firing/resolved, health, grabs, subtitle downloads |
| Live Activity only | ArgoCD, Uptime Kuma, Backrest, Proxmox, Overseerr, Gatus, Changedetection, Paperless, Unmanic, Gitea, Forgejo | Multi-step progress tracking (syncs, downloads, backups) |
| Both | Radarr, Sonarr, Jellyfin, Komodo, TrueNAS | Radarr/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 |
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.
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.
End-to-end encryption
Notifications sent through the relay are not end-to-end encrypted. The relay never holds your encryption key: it builds the text from the webhook and sends it to PushWard readable. For encrypted alerts, send them with the CLI, an MCP server you run yourself, Home Assistant, the Grafana plugin or the Unraid plugin.
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.
Poster artwork
Four providers carry artwork through to the Live Activity with no configuration on your side. Jellyfin, Radarr, Sonarr and Overseerr all know which film or episode an event is about, so the relay resolves its poster and attaches both the image URL and a ThumbHash to the activity it creates. The Lock Screen shows cover art instead of a generic download glyph.
Jellyfin in particular is usually reachable only on your own network, and the phone refuses to download an image from a private host -- so the ~25-byte blurred version travelling on the push is the only thing that renders. The relay fetches the artwork once to build that hash, which is the whole reason this works for a self-hosted media server at all.
The webhook waits at most 600ms for a hash it does not already have, then answers without one. The fetch is not cancelled: it carries on under its own ~3s budget and fills the relay-wide cache, so the very first event for a film you have never seen before arrives bare and the next update picks the artwork up. If a poster cannot be resolved at all -- an untagged file, an unreachable image endpoint -- the activity falls back to its icon exactly as before.
Artwork from a media server on your LAN
The relay will not fetch from a private address unless you tell it to. poster.allow_private_hosts is false by default, so on a stock relay a http://192.168.1.10:8096/... or jellyfin.local poster produces no ThumbHash -- and since the phone independently refuses that host too, nothing renders. Self-hosting the relay alongside the media server is the case this setting exists for:
poster:
enabled: true
allow_private_hosts: true| Variável de Ambiente | Descrição | Padrão |
|---|---|---|
PUSHWARD_POSTER_ALLOW_PRIVATE_HOSTS | Let poster fetches reach loopback, RFC 1918, CGNAT/Tailscale and link-local addresses. It is also what permits a plain http fetch; with it off the relay fetches over https only (YAML: poster.allow_private_hosts) | false |
PUSHWARD_POSTER_ENABLED | Attach poster artwork at all. Turning it off drops both the image URL and the ThumbHash (YAML: poster.enabled) | true |
Leave this off on any relay that accepts webhooks you do not control, including the public relay.pushward.app, which runs with the default. The webhook payload is what carries the image URL, so a relay that will fetch private addresses on request is an SSRF probe of everything it can reach. When it is on, the check runs against the resolved address rather than the hostname, so a DNS name pointing at 127.0.0.1 does not slip past it.
The ThumbHash encoder decodes JPEG, PNG and GIF. Artwork served as WebP or AVIF gets an image_url but no hash, so it renders only when the phone can reach the URL.
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.
| Parameter | Values | Effect | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
channels | Comma-separated: activity, notification | Restricts 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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
priority | Integer 0-10 | Sets the eviction / relevance priority for any Live Activity the request creates. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
level | passive or 0, active or 1, time-sensitive or 2, critical or 3 | Sets the notification interruption level for any push notification the request sends. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Chega na versão 1.17.0 do app | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ack | 1 or 0 | 1 repeats an alert's push until someone acknowledges it or it expires, and the resolve stops the repeats. See Acknowledged alerts. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ack_repeat | Seconds, 30-3600 (default 300) | How often the alert repeats. Needs ack=1. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ack_expire | Seconds, 60-10800 (default 3600) | How long the alert keeps repeating when nobody acknowledges it. Needs ack=1. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
retract | 1 or 0 | 1 takes a resolved alert's push back off the devices instead of sending "Resolved" over it. See Retracted alerts. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
https://relay.pushward.app/grafana?channels=notification&level=time-sensitiveAn 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.
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.
Acknowledged alerts
With ack=1, the push for a new alert repeats until someone taps Acknowledge on one of their devices, or until ack_expire runs out. The routes that send alerts take it: Grafana, Uptime Kuma, Gatus, Komodo, TrueNAS (through its own URL, below) and the alerts of the universal webhook. Only that push repeats. Resolved notifications, passive ones and the other providers' notifications go out as before, and channels=activity sends no push at all.
https://relay.pushward.app/uptimekuma?ack=1&ack_repeat=60- The resolve webhook stops the repeats: Grafana with nothing left firing in the group, Uptime Kuma UP, Gatus resolved, a Komodo condition resolved, the TrueNAS clear, a universal webhook alert clearing. The relay stops them first and sends the resolved notification after, so the remaining repeats do not land on top of it. The resolve has to reach a URL with
ack=1as well, which it does when the service posts both to the same URL. - The relay stops Grafana repeats per alert name. With a contact point that groups by instance or folder, one group resolving also stops the repeats of another group of the same alert that is still firing.
- Komodo events that never resolve (a failed build, a stopped container) repeat until someone acknowledges them or they expire. With
ack=1they are keyed on the condition (target and alert type), so the next event of the same condition replaces the repeats of the one before instead of taking another of the 25. - An account can have at most 25 repeating alerts at once, shared with everything else that sends acknowledged notifications with your keys. When it is full, or the server refuses the acknowledge for another reason, the relay sends the alert once without repeats, so it still arrives.
- An
ackother than1or0, anack_repeatorack_expirethat is not an integer in its range or comes withoutack=1, andack=1withlevel=passiveare a400. - A self-hosted relay needs version 0.17.0 or later.
TrueNAS cannot use query parameters: it appends /v2/alerts to the API URL it is given, so a query string never arrives as one. To repeat its alerts, set the API URL of its OpsGenie alert service to the URL below. Each alert then repeats every 5 minutes for up to an hour, until it is acknowledged or TrueNAS clears it.
https://relay.pushward.app/truenas/ackHow the button, the repeats and their limits work is covered on the acknowledged alerts page.
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.
https://relay.pushward.app/gatus?retract=1| Provider | Taken back | On |
|---|---|---|
| Grafana | The alert name's push | Nothing left firing under the alert name (before 0.19.1: in the group) |
| Uptime Kuma, Gatus, Komodo | The monitor's, endpoint's or condition's push | UP, RESOLVED, resolved |
| TrueNAS | The alert's push | The clear, on /truenas/retract (below) |
| Universal webhook | An alert card's push, when the preset keys it on a correlation value | The card ending |
| Radarr, Sonarr, Prowlarr | That health check's push | HealthRestored |
| Radarr, Sonarr | A download's manual-interaction push | The import (Download) of the same download |
| Overseerr / Seerr | The issue report or reopen | ISSUE_RESOLVED |
| Backrest | A failure push | The 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
retractoff 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
radarrand aradarr-4kposting 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 leaveretractoff 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=1as well, the resolve still stops the repeats first. - A
retractother than1or0is a400. - A self-hosted relay needs version 0.19.0 or later for
retract,/truenas/retractand the collapse ids below, and 0.19.1 for the Grafana groups and the Backrest retries and new ids described below. The hosted relay atrelay.pushward.appis 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.
https://relay.pushward.app/truenas/retractSetup
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:
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:
| Method | Providers | Format |
|---|---|---|
| Bearer token | Most providers | Authorization: Bearer hlk_... |
| Basic Auth | Radarr, Sonarr, Prowlarr, Bazarr, Komodo (their webhook settings only support Basic Auth) | hlk_... as password, username ignored |
| GenieKey | TrueNAS | Authorization: GenieKey hlk_... |
Configuration
| Variável de Ambiente | Descrição | Padrão |
|---|---|---|
PUSHWARD_URL | PushWard server URL | -- |
PUSHWARD_DATABASE_DSN | PostgreSQL connection string | -- |
PUSHWARD_SERVER_ADDRESS | HTTP 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.