Matrix clients receive notifications in the following ways:
- **In-band notifications**, which are shown when the client actively syncs with the server.
- **Push notifications**, which are posted to the client by the server through an external push service. This is typically used to send out-of-band notifications to mobile devices, and it is the focus of this page.
Generally, your mobile device is preconfigured for push notifications out of the box. The details below are for advanced use cases, such as using an alternative push backend (like UnifiedPush) or hosting your own.
## Overview
Continuwuity supports two push methods: the legacy **Matrix Push Gateway** and the new **Web Push** protocol. The former is currently supported by more clients, but the latter enables end-to-end-encrypted push notifications. They work as follows:
<Tabs groupId="push-ops">
<Tab label="Registration">
<img src="./push-registration.webp"
alt="Diagram showing the push registration flow, described in the text below."
_([excalidraw file of the diagrams](/guides/push-notifications.excalidraw))_
Therefore, Continuwuity's role within this system is to keep track of client-registered _pushers_ and send relevant payloads to them. To view and manage these pushers, use the [`!admin query pusher`](../reference/admin/query.md#admin-query-pusher) set of commands.
## UnifiedPush
[UnifiedPush][unifiedpush] is an open and self-hostable notifications system that is supported by many Matrix clients on Android and Linux. It is compatible with both the Web Push and Push Gateway mechanisms, and therefore requires no additional setup from the homeserver.
:::info Debugging UnifiedPush
To debug and test your UnifiedPush installation, use the [UP-Example] app for Android and the [UnifiedPush Troubleshooter] app for Linux distributions.
Normally, the push gateway URL is pre-configured by the client app. However, some clients (such as Element X) implement UnifiedPush's [Gateway Discovery] mechanism, and attempt to detect a push gateway _on the same domain as the push provider_ to use before falling back to a hardcoded one. Users of these clients can therefore self-host their own push gateway.
Per the [spec][spec-push-gateway-api], these push gateways must be available on the `/_matrix/push/v1/notify` path of said domain. To test that a push gateway is usable, make a request to it from both the homeserver and the client. The returned response should look like the following:
[ntfy][ntfy] is a widely supported UnifiedPush implementation, with an easy-to-install push app and plenty of publicly available instances. Its server includes an embedded Matrix push gateway and can be self-hosted.
Some tutorials on self-hosting ntfy can be found below:
- [Element's tutorial on Unified Push and ntfy][element-ntfy]
:::warning Avoid ntfy.sh
Avoid using the `https://ntfy.sh` push server, which is configured as the default in the ntfy app. This server is known to ratelimit requests aggressively.
Community tutorials for selfhosting some of these stacks are listed below. Unless stated otherwise, they are all tested against Element X Android and the push gateway mechanism, but they should work with Web Push as well.
- [Self-hosting Sunup for Matrix and UnifiedPush][kimiblock-selfhosting-sunup], by Kimiblock.
- Push gateway: [common-proxies]
- Push server: [autopush-rs]
- Push app: [Sunup][sunup]
- [Matrix notifications on Android, powered by XMPP][stratself-xmpp], by stratself.
Issues with push notifications can arise from the components of the system beyond your homeserver (for example, if the connection fails between the gateway and the push server). Make sure you check the logs of these components for debugging as well.
### Locally hosted push gateways / push providers
Outbound requests, including push notifications, follows the `ip_range_denylist` config option which refuses loopback and private-range destinations by default. This would break against push components that are self-hosted on a LAN address, and will result in these log entries at push creation time:
```txt
WARN conduwuit_service::pusher: Pusher URL is a forbidden remote address url=https://push.example.com/_matrix/push/v1/notify
```
To fix this, remove your push gateway or push server's address from `ip_range_denylist`, and restart Continuwuity to apply the changes.
Docker deployments with the push server/gateway on the same host as Continuwuity may run into some further network issues. In this case, consult the [Docker loopback networking issues] section and its workarounds.
This is likely an issue with your account's _push rules_, which determines which events are shown to to the user as notifications. Check these push rules in the client's notifications settings and tweak accordingly. Continuwuity also provides an [`!admin users reset-push-rules`](../reference/admin/users#admin-users-reset-push-rules) command, which restores the rules to the default of notifying for every message.
Another reason may be that push background services are frequently being terminated by your operating system, which is a [well-known problem][dontkillmyapp] with many Android-based systems. To fix this, follow your operating system's instructions to exempt your push app from background restrictions.
Otherwise, if you find Continuwuity not sending push notifications according to the spec, feel free to discuss in our [support room][support-room] or open an issue.
### Various "Could not send request to pusher" log entries
If you find spurious log entries like this in your Continuwuity deployment:
```txt
WARN push{user_id="@user:example.com" pushkey="very-long-string-of-letters" events=1}:send_push_notice:send_notice:send_request: conduwuit_service::pusher: Could not send request to pusher https//push.example.com: error sending request for url (https://push.example.com/_matrix/push/v1/notify)
#### Connection issues between the server and the push gateway
Verify that the connection to the push gateway is working correctly. This includes checking firewall rules, DNS, and that the push gateway is online. The section on [locally-hosted gateways/push providers](#locally-hosted-push-gateways--push-providers) may also apply to you.
#### Expired push endpoints
Active Matrix clients periodically renew their pushkeys as the old ones expire, and consequently register them against Continuwuity. As these pushers build up over time, the homeserver will keep sending more requests to an increasing number of "dead" push endpoints. This results in the errors seen above, and can heavily impact performance if not mitigated.
To work around this issue, the following actions can be taken:
- Delete all of a user's pushers with the [`!admin query pusher delete-all-user`](../reference/admin/query##admin-query-pusher-delete-all-user) command. This command is not typically disruptive, as active clients will re-register new pushers the next time they log on.
- Alternatively, delete one's own pushers from a client that supports doing so. Currently this only includes FluffyChat and Element Classic/SchildiChat Legacy.
While clients are supposed to automatically delete old pushers under their own control, this behaviour has been inconsistent. A further discussion of this issue can be found in [#2242][issue-2242].
