Skip to main content
API docs by Redocly

Event stream configuration API (1.0)

Download OpenAPI specification:Download

Integration registration

List registered integrations

Lists all configured integrations.

Authorizations:
newStoreAccessToken

Responses

Response samples

Content type
application/json
{
  • "integrations": [
    ]
}

Register new integration

Registers a new integration. You can specify how the events will be sent to you:

  • via the webhook. The events are provided in real time.
  • via file upload to the S3 bucket of your choice. An upload typically occurs every 5 minutes.

By default, you will receive all the events that NewStore can provide. To only receive specific events, use the filter_conditions property to set filters on entities and/or events. To see all entities and events, see the entity model.

When you call this method, the integration starts automatically, you do not need to call the Start integration method. At most 10 integrations can be registered.

You can also use this method to replay events by date. To do this, set a start and end date when you call this method. The use of an end date registers a temporary integration that will receive all events that were emitted between the start and end date. When the last event of the end date is emitted, the integration is automatically stopped.

In case of webhook integration, if you use the api_key property then every call to the URL set in the callback_url property includes the line Authorization: Bearer <api_key> in its header.

In case of S3 integration, the events are stored in multiple files with the following name: s3://{bucket}/{key_prefix}/{tenant}/{timestamp}-data-{random_string}.export, where:

  • bucket and key_prefix are the parameters you specified in s3_parameters.
  • timestamp is the time, when the file was created on the server, in epoch millis.

Every file contains multiple JSON objects, one per event, delimited by a newline character. The events are described with the same schema as in the webhook.

A new file is started every 5 minutes, or when the size of the current file reaches 50 MiB, whichever happens first.

Note: The start and end date as well as integration type can not be modified after creation.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
One of
required
object (Webhook Parameters)

Configuration parameters for webhook's callback.

id
required
string [ 1 .. 50 ] characters ^[a-z0-9-]+$

The identifier for this integration. It must be a unique value consisting of lowercase alphabetic characters, numbers and dashes. An example would be erp-1.

integration_type
required
string
Enum: "temporary" "permanent"

Type of the integration. Temporary integrations can not be updated and will be deleted automatically once the last event has been sent.

starts_at
string <date-time>

UTC timestamp from which events are being emitted. Must not be in the future. Optional for permanent integrations and mandatory for temporary integrations.

ends_at
string <date-time>

UTC timestamp until which events are being emitted. Not available for permanent integrations. Mandatory for temporary integrations.

object or object

Configuration parameters for event- and entity-type filtering.

Responses

Request samples

Content type
application/json
{
  • "webhook": {
    },
  • "aws": {
    },
  • "webhookEntityAndEventFilters": {
    },
  • "webhookEntityFilters": {
    },
  • "webhookEventFilters": {
    }
}

Response samples

Content type
application/json
{
  • "id": "sap-integration-001",
  • "status": "running",
  • "integration_type": "temporary",
  • "starts_at": "2019-01-17T12:00:00.000Z",
  • "ends_at": "2019-02-21T23:59:00.000Z",
  • "callback_parameters": {}
}

Update the integration

Updates the specified integration and returns the updated state.

Important: Stop the integration before you update it.

The typical update workflow is:

  1. Stop the integration using the Stop integration method.
  2. Poll the Get integration method until status is stopped.
  3. Update the integration using the Update integration method.
  4. Start the integration using the Start integration method.
Authorizations:
newStoreAccessToken
path Parameters
integration_id
required
string

Unique identifier of the integration.

Request Body schema: application/json
object (Webhook Parameters)

Configuration parameters for webhook's callback.

object (S3 Parameters)

Configuration parameters for upload to amazon s3.

object or object

Configuration parameters for event- and entity-type filtering.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "sap-integration-001",
  • "status": "running",
  • "integration_type": "temporary",
  • "starts_at": "2019-01-17T12:00:00.000Z",
  • "ends_at": "2019-02-21T23:59:00.000Z",
  • "callback_parameters": {}
}

Get integration details

Returns details about an existing integration.

Authorizations:
newStoreAccessToken
path Parameters
integration_id
required
string

Unique identifier of the integration.

Responses

Response samples

Content type
application/json
{
  • "id": "sap-integration-001",
  • "status": "running",
  • "integration_type": "temporary",
  • "starts_at": "2019-01-17T12:00:00.000Z",
  • "ends_at": "2019-02-21T23:59:00.000Z",
  • "callback_parameters": {}
}

Delete the integration

Deletes an existing integration.

Authorizations:
newStoreAccessToken
path Parameters
integration_id
required
string

Unique identifier of the integration.

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "request_id": "string"
}

Integration operation

Start the integration

Starts the specified integration. NewStore Omnichannel Cloud starts emitting events to the receiving URL.

You can check the status of the integration with the Get integration method.

Note: When an integration was stopped, it must be restarted within 30 days in order to receive all events which occurred while it was stopped. If the integration gets restarted more than 30 days after being stopped, it will only receive events which occurred after the point in time when it was restarted.

Authorizations:
newStoreAccessToken
path Parameters
integration_id
required
string

Unique identifier of the integration.

Responses

Response samples

Content type
application/json
{
  • "id": "webhook-integration-1",
  • "status": "running",
  • "callback_parameters": {},
  • "integration_type": "permanent",
  • "starts_at": "2019-07-07T00:00:00Z"
}

Stop the integration

Stops the specified integration. No events are emitted once the integration is stopped.

You can check the status of the integration with the Get integration method.

Authorizations:
newStoreAccessToken
path Parameters
integration_id
required
string

Unique identifier of the integration.

Responses

Response samples

Content type
application/json
{
  • "id": "webhook-integration-1",
  • "status": "stopped",
  • "callback_parameters": {},
  • "integration_type": "permanent",
  • "starts_at": "2019-07-07T00:00:00Z"
}

Get integration log

Returns the last 50 integration log entries.

Authorizations:
newStoreAccessToken
path Parameters
integration_id
required
string

Unique identifier of the integration.

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ]
}

Rejected events

List rejected events

Lists the events that were rejected by the integration (HTTP status code 400).

Up to 30 rejected events are stored. To delete some events, use the Delete rejected event method.

Authorizations:
newStoreAccessToken
path Parameters
integration_id
required
string

Unique identifier of the integration.

Responses

Response samples

Content type
application/json
{
  • "rejected_events": [
    ]
}

Get rejected event

Get the payload of the rejected event.

Authorizations:
newStoreAccessToken
path Parameters
event_id
required
string

Unique identifier of the rejected event.

integration_id
required
string

Unique identifier of the integration.

Responses

Response samples

Content type
application/json
{
  • "tenant": "businessname",
  • "name": "order.items_cancelled",
  • "published_at": "2010-01-01T12:00:00.000Z",
  • "payload": {
    }
}

Delete rejected event

Deletes the rejected event permanently. NewStore stores 30 rejected events so we recommend that you delete the rejected events that you have handled.

To list all the rejected events, use the List rejected events method.

Authorizations:
newStoreAccessToken
path Parameters
event_id
required
string

Unique identifier of the rejected event.

integration_id
required
string

Unique identifier of the integration.

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "request_id": "string"
}

Retry rejected event

Sends the rejected event to the defined endpoint of the integration again.

In case the integration responded with a 200 response code, the rejected event will be automatically removed from the rejected event list.

Authorizations:
newStoreAccessToken
path Parameters
event_id
required
string

Unique identifier of the rejected event.

integration_id
required
string

Unique identifier of the integration.

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "request_id": "string"
}