OneSignal user identity and event specification kit

A OneSignal User is a profile; a Subscription is a channel recipient such as a device or email address. Linking a stable service member ID as an External ID connects relationships across devices and channels. Keep the internal user_id, OneSignal user ID, and Subscription ID in distinct fields. OneSignal Users

Do not use workspace_id as the External ID when several people belong to an organization. It identifies the organization, not the individual. Use the internal member's user_id and keep workspace, invitation, and task relationships as business correlation keys. Use the integration guide and onboarding checklist to review the existing login flow and member data first.

Link the user with OneSignal.login when a stable ID for the authenticated member is available. Web SDK logout removes the current browser's identified relationship and creates an anonymous context. It does not delete every device's subscription or the entire member record. OneSignal Web SDK reference

Service registration, SDK data collection settings, marketing consent, operating-system notification permission, and channel subscription are separate states. Do not mark the other states as allowed because registration or login succeeded. Specify each source of truth, update owner, and point at which a change excludes the user from sending.

Preserve the member ID that applied when an event occurred during an account change. Replacing it with the currently logged-in member during delayed processing assigns the action to another person. For account deletion, assign owners for the OneSignal deletion scope and for queued deliveries and reprocessing jobs. Check whether a remaining integration job can recreate the user. OneSignal Delete users

IXC-DEMO-01 guides an invited user toward completing a shared task in a fictional B2B collaboration service. The member is usr_demo_01, workspace ws_demo_01, and invitation inv_demo_01. invitation_accepted means the invitation server committed acceptance. shared_task_completed means the task server committed completion of the associated shared task. Live-account event delivery and message receipt tests have not been performed.

The example permits one active invitation per user. When creating the shared task, the backend stores which invitation it follows. Match user_id, workspace_id, and invitation_id across the two events to connect entry and completion. Do not count completion from another workspace or a task whose invitation relationship cannot be established.

Define current membership and personalization state as user properties, and acceptance and completion at particular times as events. Keep the action's meaning in the name and put workspace or campaign IDs in properties. OneSignal Custom events distinguishes events from persistent profile state. The journey design workbook connects these definitions to the overall flow.

The internal contract includes string fields user_id, workspace_id, and invitation_id; an event-specific UUID event_id; UTC occurred_at and received_at timestamps; and integer schema_version. occurred_at records the committed business action; received_at records arrival at the relay server. Keep both to identify delay and out-of-order arrival.

The acceptance example uses name=invitation_accepted, user_id=usr_demo_01, workspace_id=ws_demo_01, invitation_id=inv_demo_01, campaign_id=IXC-DEMO-01, and schema_version=1. Its event_id is 0a16ce21-7e35-4f9e-a5ac-9a331944ab01 and occurred_at is 2026-09-10T01:00:00Z. Retry the same acceptance with the same event_id. Task completion uses the same business relationship with a new event ID and completion timestamp.

Inside the OneSignal request's events array, map user_id to external_id, occurred_at to timestamp, and event_id to idempotency_key. Use name for the event name and place workspace_id, invitation_id, campaign_id, and schema_version in properties. Keep received_at in relay observability records. Task text and invitation tokens are not required decision fields for this campaign. Create custom events API

Quarantine a missing member or invitation ID instead of supplying a shared fallback. For a repeated event_id, consult the processing ledger and prevent another business action. OneSignal's identical-idempotency-key suppression is best effort over four hours, so it does not replace an internal ledger. HTTP 202 may contain per-event errors; do not mark an entire batch successful solely from its status. Create custom events API error and duplicate handling

When completion arrives before acceptance, the expected outcome is to preserve the completed state and exclude the reminder. A late acceptance must not revert the task to incomplete. Supplying timestamp alone does not establish correct ordering. Compare final source state, occurrence time, receipt time, and processing history.

Completion in another workspace must not affect the current task. Block residual event delivery after account deletion and record cleanup. After fixing a failed user association, reassess completion and consent. Recovery is not a reason to replay an old reminder immediately.

For every event, document meaning, producer, required fields and types, consuming journeys and metrics, and valid and invalid examples. Connect each expected outcome to the actual result and log location. Mark unexecuted tests as not run, with a reviewer and next action. The downloadable PDF and worksheets are in English.

Reflect changes to a field's name, type, or meaning in schema_version and the change log. Agree on the period when old and new versions coexist, affected journey rules and measurement queries, and rollout and recovery steps. Use the inputs in the CRM campaign QA material and assess unresolved conditions as READY, READY WITH CONDITIONS, or HOLD.

IXC's customer data integration service defines required events and properties and implements identity and event delivery or reviews the development team's implementation. Use the specification to agree on data sources, ownership, error handling, measurement-tool responsibilities, and acceptance tests. Initial SDK preparation connects to OneSignal onboarding.