Sending a push notification to one device sounds simple: identify the device and send a message to it. In production, the difficult part is not the HTTP request. It is maintaining a reliable relationship between your application, the device’s current push token, the user’s identity, and the targeting identifier used by your notification service.

HoneyNotify supports server-side notification sends through POST /v1/notifications. Requests use a Bearer API key and an Idempotency-Key, and each notification requires a title, body, and target. For a single-device notification, the target should address that specific device rather than a user, tag, segment, or all enabled devices.

This guide explains the end-to-end process, the design choices behind device targeting, and the failure modes that commonly cause notifications to reach the wrong place or not arrive at all.

What “one device” means

A device target is a notification destination representing one registered app or browser installation. It is not necessarily the same thing as a person, account, browser profile, or physical handset.

That distinction matters because one person may have several destinations:

  • An iPhone and an Android phone can both belong to the same user.
  • A user may be signed in on several browsers.
  • Reinstalling an app can create a new push-token relationship.
  • A browser can lose permission or generate a new token.

Use a device target when the event is specific to one installation. Examples include confirming an action on the device that initiated it, refreshing data after a local state change, or notifying a particular browser session about an active workflow.

Use a user target instead when the message should reach every eligible device associated with an account. Choosing the wrong level of targeting can either miss a user’s other devices or expose a private event to destinations that should not receive it.

The targeting flow

A dependable single-device send normally has four stages.

1. Register the device in the client

Use the HoneyNotify client SDK for the relevant platform. The SDKs cover device registration, identity, token lifecycle, payload handling, and lifecycle events across iOS, Android, and Web Push.

Registration should happen as part of a deliberate application flow, not only during the first launch. The operating system may delay permission decisions, the user may sign in later, or a browser may become eligible for notifications after an interaction.

Your application should record the device identifier returned or established by the registration process according to HoneyNotify’s current SDK documentation. Treat that identifier as data associated with a destination, not as a permanent property of the physical hardware.

2. Associate the device with the right application state

If your product has accounts, associate the registered device with the signed-in user through the SDK’s identity capabilities or your own server-side model, following the documented HoneyNotify flow.

Keep enough internal information to answer these questions:

  • Which application environment created this device record?
  • Which user, if any, is currently associated with it?
  • When was the device last registered or refreshed?
  • Is the destination still allowed to receive this category of notification?

Avoid treating a client-supplied device identifier as proof of account ownership. Authentication and authorisation should determine which server-side operation is allowed to send to a destination.

3. Store the destination reference safely

Your backend needs a reliable way to select the intended device when an event occurs. Store the HoneyNotify device reference with the relevant application record, subject to your data-retention and privacy requirements.

Do not put a secret API key in an iOS, Android, or browser client. The server should decide whether a notification is allowed, construct the request, and send it using the Bearer API key. A client may request an action, but it should not be able to send arbitrary messages to arbitrary device targets.

4. Send from the server

Send a POST request to /v1/notifications with the Bearer API key, a unique Idempotency-Key, and the required notification fields: title, body, and a target that identifies the one device.

The exact target representation and request formatting should follow the current HoneyNotify API documentation. Do not infer a target schema from another provider or from a legacy integration. Validate that the selected target is the device destination you intended, rather than a user, tag, segment, or broad audience.

The Idempotency-Key is important when your application retries a request after a timeout or transient failure. Generate it for the logical send operation and reuse it when retrying that same operation. Do not create a new key for every retry, or the service may reasonably treat each retry as a separate send.

Choosing a device identifier

A device identifier should be treated as a provider-facing destination reference with a lifecycle. It may remain usable while the underlying push token remains valid, but that relationship can change.

Push tokens can rotate because of operating-system behaviour, app reinstalls, permission changes, provider changes, or other platform events. The client application should use the SDK’s token lifecycle support and keep the server-side destination data current.

A practical design is to make registration and token refresh idempotent in your own backend. When the SDK reports a new or changed token, update the corresponding device record rather than blindly creating an additional destination. Also define what happens when a user signs out: depending on your product’s privacy and notification model, you may need to disassociate the user while retaining the device registration for a later sign-in.

Do not use a user ID as a substitute for a device ID. A user ID describes an account; it does not identify one delivery destination. Similarly, do not assume that a device identifier will remain unchanged across app environments such as development and production.

Handling imported device identifiers

If you are migrating from OneSignal, imported OneSignal subscription IDs can remain as device IDs when matching provider tokens later register. This can make a staged migration possible without requiring every destination to be rebuilt immediately.

There are important limits to this approach. Token rotation or registration from another provider environment can prevent a later token from matching the imported identifier. Build reconciliation into the migration rather than assuming that every imported record will continue to resolve automatically.

Useful safeguards include:

  • Keep the old provider’s environment information during the migration.
  • Record when a device registers again and which token lifecycle event triggered the update.
  • Test fresh installs, reinstalls, token changes, and environment changes separately.
  • Avoid deleting an old destination solely because a newly registered destination does not match immediately.
  • Define a controlled process for retiring records that remain unusable after your chosen migration period.

Delivery and application behaviour

A successful API request means the notification request was accepted for processing; it does not mean the user has already seen it. Delivery can still be affected by platform permission, device connectivity, operating-system policies, notification settings, and application state.

The client SDK’s payload handling and lifecycle events help the application respond when a notification is received or opened. Keep the notification payload focused on the information the client needs to navigate or refresh state. Do not place sensitive data in a push payload merely because the target is a single device: the destination may be shared, compromised, or displayed by the operating system.

For actions that change server-side state, the client should fetch authoritative data from your backend after opening the notification. A push notification should prompt or synchronise the application, not act as the only source of truth.

Common mistakes

Sending from the client

Embedding a Bearer API key in a mobile or web application exposes the credential to users and attackers. Keep notification sends on a trusted server.

Using a broad target accidentally

A user, tag, segment, or all-enabled-devices target can deliver to more destinations than intended. Make the target type explicit in your notification service code and add tests for single-device operations.

Reusing an old device reference forever

A stored identifier may no longer map to the current provider token. Process registration and token lifecycle events, and provide a way to disable or refresh stale destinations.

Creating a new idempotency key during retries

This can turn one logical event into multiple notifications. Persist the key with the send operation until the request has reached a final state according to your retry policy.

Assuming an accepted request proves delivery

Log request identifiers, target references in a privacy-conscious form, response status, retry decisions, and client lifecycle events. Use these records to distinguish an API problem from a permission, token, or device-state problem.

Confusing a physical device with an installation

Design for multiple installations per user and for replacement or reinstallation. Your data model should allow destinations to be added, refreshed, disassociated, and retired without corrupting the user’s account.

A practical test plan

Before enabling one-device notifications in production, test the complete lifecycle:

  • Register a new iOS, Android, and Web Push destination where those platforms apply to your product.
  • Send to exactly one destination and confirm that other signed-in destinations do not receive the message.
  • Test a signed-out device and a device changing accounts.
  • Rotate or refresh the push token and verify that the destination remains current.
  • Retry a timed-out send with the same Idempotency-Key.
  • Test denied permissions, disabled notifications, offline devices, and app reinstalls.
  • Verify that notification opens lead to an authorised server-side data fetch.
  • Test development and production environments independently.

Conclusion

Targeting one device with HoneyNotify requires more than selecting a device-shaped target. Register the destination through the client SDK, associate it with application state securely, keep its token relationship current, and send from your server with the required authentication and idempotency controls. Treat device targeting as a lifecycle rather than a permanent identifier, and single-device notifications will be easier to secure, troubleshoot, and operate reliably.