Notification Flows
How notifications are delivered across Cloud, Self-Hosted, and External Systems
Cloud (Direct APNs)
When the backend has direct access to Apple Push Notification certificates, notifications are sent straight to push networks without intermediaries.
Self-Hosted (Passthrough)
Self-hosted instances without Apple certificates delegate iOS push delivery to the Zentik Cloud relay. The relay never sees the decrypted payload — it forwards the opaque encrypted package to APNs on behalf of the self-hosted server. Android (FCM) and Web Push are sent directly.
A passthrough token is required for self-hosted iOS delivery. Request one here.
External Systems (Ntfy / Gotify)
Zentik acts as a bidirectional proxy for external notification systems. Incoming messages are mapped to Zentik notifications and delivered through the standard push pipeline.
When a Zentik bucket is linked to an external channel, the backend subscribes to the external system and automatically creates notifications for incoming messages. Outgoing messages sent to that bucket are also published back to the external system.
iOS Delivery Strategies
APNs enforces a 4 KB payload limit. When rich notifications exceed this limit, the backend automatically falls back through three strategies:
| Strategy | When used | Privacy |
|---|---|---|
| ENCRYPTED | Default — full content encrypted with device key | End-to-end encrypted |
| UNENCRYPTED | Fallback if encrypted payload too large (user opt-in) | Plaintext via push network |
| SELF_DOWNLOAD | Last resort — device fetches content from server | Content never leaves server via push |
For the full decision flowchart, configuration details, and how to enable the unencrypted fallback, see Delivery Strategies.