--- source_url: https://www.pubnub.com/docs/data-storage/structured-data/events title: DataSync events updated_at: 2026-09-30T07:20:08.000Z --- # DataSync events ## Documentation index To discover more PubNub resources: 1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format. 2. Identify relevant URLs from that index. 3. Fetch the target pages. Do not assume a path exists, always check the index first. DataSync events are regular PubNub messages delivered on regular channels. Your app receives them the same way it already does for messaging. Any create, update, or delete of a DataSync object can publish an event. When an entity changes, every client subscribed to the right channel receives the new state without polling. Events use [message type](https://www.pubnub.com/docs/pub-sub/overview.md#message-types-categorize-traffic-on-a-shared-channel) 5, which distinguishes them from ordinary messages. ## Enable DataSync events Events are off by default. You turn them on per class version, per keyset, in the [Admin Portal](https://admin.pubnub.com), using event rules. A rule is all-or-nothing: it enables create, update, and delete events together. There's no way to select individual verbs. This applies to entities and relationships you define, and to the built-in users, channels, and memberships. Each class version is enabled separately. To see which classes and versions exist on your keyset, list them with [Get all entity class entries](https://www.pubnub.com/docs/admin-api/get-all-entity-class-entries.md) and [Get all relationship classes](https://www.pubnub.com/docs/admin-api/get-all-relationship-classes.md). :::note Enabling a rule isn't retroactive A rule is read when the write happens, and the result is cached for up to five minutes. Turning a rule on can take that long to affect new writes, and it never applies to writes that already happened. Objects written while events were off don't produce events later. ::: For step-by-step instructions, refer to [Enable DataSync](https://www.pubnub.com/docs/data-storage/structured-data/enable-structured-data.md). ## Where events are published Every entity has an ID channel, named after its own ID, and every event about that entity publishes there. ```mermaid flowchart LR CREATE["Entity create
product-sneaker-42"] CHANGE["Entity update or delete
product-sneaker-42"] RELATIONSHIP["Relationship or membership event
no channel of its own"] PRODUCT["product-sneaker-42
ID channel"] LINKED["seller-bob
linked entity ID channel"] USER["user-alice
ID channel"] CHANNEL["channel-summer-sale
ID channel"] CREATE --> PRODUCT CHANGE --> PRODUCT & LINKED RELATIONSHIP --> USER & CHANNEL ``` ### Entity events For an entity: * A **create** event publishes only to the entity's ID channel. A newly created entity has no relationships yet, so there's nowhere else to reach. * An **update** or **delete** event publishes to the entity's ID channel, plus the ID channel of every other entity it's currently linked to by a relationship. ### Membership and relationship events Relationships and memberships have no ID channel of their own. Every relationship event (create, update, or delete) publishes to both of its linked entities' ID channels instead. A delete event follows the same routing as any other event. For an entity, it's published to its own ID channel plus the ID channels of its linked entities. For a relationship or membership, it's published to the ID channels of both linked entities. Deleting an entity also deletes the relationships linked to it, and each of those cascaded deletes publishes an event of its own. Deleting an entity with three relationships produces one entity-delete event plus three relationship-delete events. :::warning A relationship or membership handle receives nothing for the link itself Relationship and membership events never reach a channel named after the relationship or membership ID. Subscribe to the two linked entities instead. ::: ### Projection channels Every change fans out to one event per projection declared on the class: * The object's own ID channel carries the `__default__` view of the payload. * Each named projection declared on the class has a channel of its own, `____`, carrying that projection's view. In other words, an event's payload is scoped to the channel it arrives on. A client subscribed to the object's own ID channel sees only `__default__` fields. A client that needs a restricted projection subscribes to the corresponding `____` channel instead. `status` is scoped the same way `payload` is. A class that declares no `/status` property treats it as `__default__` only. The other system fields (`id`, `eTag`, `createdAt`, `updatedAt`, `expiresAt`) are identical on every channel. A delete event has no payload or status, so the same `{ id, deletedAt }` body reaches every one of those channels. If a class declares no properties at all, a single unfiltered event publishes to the object's own ID channel. Publishing to a projection channel is an ordinary channel publish. Use [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md) channel grants to control who can subscribe to a projection channel. Refer to [Projections](https://www.pubnub.com/docs/data-storage/structured-data/projections.md#projections-and-events). ## How events relate to subscribe DataSync events arrive through the same subscription and listener infrastructure you already use for messages, signals, and [presence](https://www.pubnub.com/docs/presence/overview.md) events. You subscribe to the channels an object's events reach and handle messages with message type 5. A common pattern is to fetch the object once to get its current state, then apply incoming events to keep that state current. DataSync publishes each change event at least once, so a subscriber can receive the same event more than once. Compare `eTag` or `updatedAt` on each incoming event against the state you hold, and discard events you've already applied. The at-least-once guarantee covers publishing. Receiving follows the same rules as any other message on the live subscribe path: Live delivery to subscribers is at-most-once by default. On a stable connection, a subscriber receives each message at most once. After a reconnect, a replayed message can arrive again with the same timetoken. A subscriber can also miss messages if its buffer overflows or if it's disconnected when someone publishes a message. An event missed during a disconnect isn't sent again. When the [status listener](https://www.pubnub.com/docs/architecture/connection-management/overview.md#the-status-listener) reports a reconnect, fetch the object again to get its current state. Events for the same object arrive in order. Events for different objects can interleave, and there's no ordering guarantee across objects or across channels. For code examples, refer to [Subscribe to events](https://www.pubnub.com/docs/data-storage/structured-data/subscribe-to-events.md). ## Event format For the full wire format, field reference table, and event type examples, refer to [Event format reference](https://www.pubnub.com/docs/data-storage/structured-data/event-format.md). Last updated at: 2026-09-30T07:20:08.000Z