---
title: "Receiving real-time data"
slug: "receiving-real-time-data"
tags: ["integration", "platform", "event stream ", "order", "events", "api", "data import"]
updated: 2025-06-05T12:55:59Z
published: 2025-06-05T12:55:59Z
canonical: "docs.newstore.com/receiving-real-time-data"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Receiving real-time data

NewStore allows you to receive near real-time data from NewStore Omnichannel Cloud via NewStore **Event Stream**. The event stream consists of all the **events** emitted by the **entities** of NewStore Omnichannel Cloud. Each event contains data that can be integrated, persisted and aggregated in your data warehouse.

- `Entity`: Represents a business concept that emits events. Example: `order`, `return` or `fulfillment request`.
- `Event`: Represents a key moment of the life time of an entity. Example: `order created`, `order canceled` or `fulfillment request assigned`. All the events are described in [Event stream webhooks](https://docs.newstore.net/api/webhooks/stream_webhook_sink_hook).

## API vs event stream

An API and the event stream differ fundamentally: an API is a **pull** system, which means that you decide when to query the API. The event stream is a **push** system, which means that you receive a continuous flow of data sent by NewStore. See [Subscribing to the event stream](/v1/docs/receiving-real-time-data#subscribing-to-the-event-stream) for more information.

The event stream is designed to be used along other APIs. NewStore offers the following APIs:

- [API Explorer](https://docs.newstore.net/api/)
- [Configuration APIs](/v1/docs/configuration-apis#nesapi)
- [GraphQL API](/v1/docs/graphql-api#graphql)

## Entity model

The stream contains data about various entities. To process the data according to your requirements, see the following diagram showing the entity relationships and events:

![](https://cdn.document360.io/c2d22fcd-a44b-4e1e-bf3a-84f0ffba0dbe/Images/Documentation/a2884aac-9724-404d-b172-f87c1893ae22.png)

The entity model contains all events that can be emitted. Each event is emitted when an order/item reaches a specific step in the order management workflow.

Each event is described in [Event stream webhooks](https://docs.newstore.net/api/webhooks/stream_webhook_sink_hook).

> [!TIP]
> Note
> 
> The same entity is used for the [GraphQL API](/v1/docs/graphql-api#graphql).

**Exchanges in the event stream**

In the case of an [item exchange](/v1/docs/using-newstore-associate-app#exchanging-items) , NewStore will create a new order. You can recognize an exchange order when the `is_exchange` property is set to `true` in the `order created` and `order opened` events.

Payment account events are published in case of uneven exchanges where the customer pays or receives a refund.

## Subscribing to the event stream

Event stream supports 2 ways of consuming the events: via a `webhook` or S3 export.

The webhook way provides the data in real-time. The S3 export integration stores the events in the S3 bucket of your choice so you can process them at any time.

To subscribe to the event stream:

1. Create a new configuration using the [Register new integration](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api#operation/registerIntegration) method.

Choose between receiving the data via **webhook** (real time) or via **file upload** to the S3 bucket of your choice.
2. Implement the [Event stream webhooks](https://docs.newstore.net/api/webhooks/stream_webhook_sink_hook).

The event stream service emitting the events expects a response from the client. If no `200` response is received after retrying, the service stops emitting, assuming the receiving side must be fixed. To get the current status of your integration you can use [Get integration](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api#operation/getIntegration). Events that do not receive a successful 2xx HTTP response will be retried up to 10 times, using an exponential back-off strategy over approximately 20 minutes. Special handling applies to 400 responses, which are detailed in the next section.

Once the integration is working again, call the [Start integration](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api#operation/startIntegration) method to have the service emit events again, picking up where it stopped earlier.

If you want to stop the integration you can use [Stop integration](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api#operation/stopIntegration).

## Managing rejected events

When an integration responds with a `400` status code, the latest event is considered `rejected`. It is stored in a database to be processed later. The number of rejected events [is limited](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api#operation/listRejectedEvents). The integration receives events until the limit is reached. When the limit is reached, the integration is automatically stopped.

When an integration is stopped, we recommend you perform the following steps:

1. Call [List integration log entries](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api#operation/listIntegrationLogEntries) to learn why the integration was stopped.
2. Call [List rejected events](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api#operation/listRejectedEvents) to retrieve the list of rejected events for the integration.
3. Handle the rejected events with one of the following actions:
  - Retry them using the [Retry rejected event](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api#operation/retryRejectedEvent) method.
  - Permanently delete them using the [Delete rejected event](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api#operation/deleteRejectedEvent) method.

> [!TIP]
> Note
> 
> Each rejected event must be handled individually. If your integration was stopped because too many events were rejected, it is recommended to first handle all rejected events from the list before restarting the integration. Otherwise the integration will get stopped instantly with the next rejected event.

## Managing duplicate events

You can receive data from NewStore via [Event stream webhooks](https://docs.newstore.net/api/webhooks/stream_webhook_sink_hook), as NewStore supports emitting data at least once to your integration point. However, [Event stream webhooks](https://docs.newstore.net/api/webhooks/stream_webhook_sink_hook) sometimes deliver events more than once.

As an integrator, it is **your** responsibility to check and minimize the impact of duplicate events on the systems collecting and persisting data from the event stream (such as `NetSuite`). When you integrate with NewStore Omnichannel Cloud, it is essential that you follow these best practices to ensure your implementation is [idempotent](https://en.wikipedia.org/wiki/Idempotence):

- Make the idempotency implementation part of your product design process.
- Use an environment variable to enable or disable idempotency in your implementation. If you disable idempotency, the events that are emitted again can pass through to your integrated system.
- When a duplicate event is detected, create a log entry but do not initiate an error as duplicate events are expected.
- Store the idempotency data in AWS DynamoDB (or a similar database from another provider) as it has a high throughput. Use TTLs (30 days) to automatically delete the expired data.
- Sometimes the idempotency key of an event is composed of multiple event attributes. Ensure that the order of event attributes does not impact the idempotency key.

## Managing payment events

Retailers and partners who consume events via the Event Stream will also receive the payment account events as part of the data. Within the `payment_account` events, the rounded amounts are used when rounding is part of the configuration. When a cash transaction is completed, and a rounded total of say `AU $233.90` is captured within the cash drawer, this amount is also reflected within the `payment_account.amount_authorized` event for that transaction.

A new property (`rounded_amount`) is now added to the `payment_account.amount_authorized` event payload in the `extended_attributes` section of a transaction. See the schema [here](https://docs.newstore.net/api/webhooks/stream_webhook_sink_hook#operation/publishEvent).

This new property represents the `rounded_amount` value, which indicates the result of the rounding logic for a given transaction, the rounded total of the cash transaction. For example, if the amount of a transaction is `AU $233.87` and the `rounded_amount` displays `AU $233.90`, this would indicate that 3 cents was rounded up on the transaction. If the `rounded_amount` displays `AU $233.85` this would indicate that 2 cents was rounded down on the transaction.

::: note

If there is no cash rounding done for the transaction, the `rounded_amount` property is not present.

:::

The `rounded_amount` value is the order amount received into the platform.

**Related topics**

- [Event stream webhooks](https://docs.newstore.net/api/webhooks/stream_webhook_sink_hook)
- [Managing inventory sync with the Event stream](/v1/docs/managing-inventory-sync-with-the-event-stream#inventory-sync-es)
- [Syncing inventory after a receiving transaction](/v1/docs/syncing-inventory-transactions-using-the-event-stream#syncing-inventory-after-a-receiving-transaction)
- [GraphQL API](/v1/docs/graphql-api#graphql)
- [Event stream webhook integrations](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api)
- [Get integration](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api#operation/getIntegration)
- [Start integration](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api#operation/startIntegration)
- [Stop integration](https://docs.newstore.net/api/integration/eventstream-graphql/stream_webhook_sink_api#operation/stopIntegration)