Concepts
Push Notification Handoff
The process of waking or notifying offline devices after durable message acceptance without making push providers the source of truth.
Concepts Covered
- Push notification handoff
- Offline wake-up signals
- Push provider isolation
- Notification tokens
- Privacy-preserving payloads
- Retry and backoff
- Push vs durable delivery
- Provider failure handling
Definition
Push notification handoff is the process of creating a notification task after a message is accepted, then sending that task to a mobile platform provider or notification service so an offline device can be alerted.
The key word is handoff.
Push is not the message system itself. Push is a secondary path that tells the device, "you may have something to fetch." The actual message should remain in the platform's durable message store or sync log.
This distinction protects reliability. A push provider can be slow, rate limited, unavailable, or allowed to drop notifications. A serious messaging system should still deliver the message when the device reconnects.
The Pain That Forces Push Handoff
Phones do not keep every app fully awake forever.
Operating systems restrict background activity to save battery, reduce network usage, and protect user experience. A chat app may not have an active realtime connection when the user locks the phone or the OS suspends the app.
Push notifications solve the reachability problem:
message accepted
-> recipient offline
-> create push task
-> provider wakes device or shows alert
Once the app wakes or the user opens it, the client should sync with the backend. The push payload may contain a small alert, but the backend remains the source of truth.
Push Should Not Block Message Acceptance
The sender should not wait for push delivery before seeing that the message was sent.
Push providers are external dependencies, and external dependencies should not sit inside the critical durable write path.
A healthier flow:
1. Message API validates and stores the message.
2. Message API writes an outbox or delivery event.
3. Delivery workers identify offline devices.
4. Push task is enqueued.
5. Push workers call provider APIs with retries and backoff.
6. Recipient device later syncs from durable backend state.
If the provider is down, message acceptance still works. Online recipients still receive realtime delivery. Offline recipients receive the message when they reconnect, even if the notification was delayed or lost.
What A Push Task Contains
A push task usually needs routing metadata:
push_task
- task_id
- user_id
- device_id
- provider
- notification_token
- conversation_id
- message_id
- collapse_key
- attempt_count
- next_attempt_at
This task should be retryable and idempotent. If a worker crashes after sending to the provider, the system may retry. Duplicate push notifications are less severe than lost messages, but they still hurt product trust.
Payload Privacy
The payload itself should be carefully designed.
In privacy-sensitive messaging products, the notification may say only:
New message
instead of including message text.
Even when plaintext previews are allowed, the system should avoid putting sensitive backend-only metadata into a third-party provider payload. Push providers are outside the core trust boundary.
Provider Failures
Push providers can fail in several ways:
| Failure | Why it matters | Better response |
|---|---|---|
| Provider outage | Offline users are not alerted | Retry push separately; preserve durable sync |
| Invalid token | Device cannot be reached | Mark token stale and refresh on next app open |
| Retry storm | Push workers amplify provider failure | Use backoff, jitter, and provider-level limits |
| Duplicate push | User sees repeated notifications | Use collapse keys and idempotent push tasks |
| Sensitive payload leak | Provider sees too much content | Send minimal or encrypted notification content |
Operational Reality
Important signals:
- push task creation rate
- provider request latency
- provider error rate
- invalid token count
- retry queue depth
- notification collapse rate
- push-to-sync conversion rate
- age of oldest pending push task
- dead-lettered push tasks
These metrics help operators distinguish "messages are not being delivered" from "notifications are delayed but sync still works."
Related Topics
Knowledge links
Use these links to understand what to know first, where this idea appears, and what to study next.
Prerequisites
Read these first if this topic feels unfamiliar.
Used In Systems
System studies where this idea appears in context.
Related Concepts
Core ideas that connect to this topic.
Related Patterns
Reusable architecture moves built from these ideas.