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 25 integrations can be registered (including temporary and stopped integrations).

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 which will receive all events that were created between the start- and end date. After the last event before the end date is published, the integration is automatically stopped. You can then use the Delete integration method to delete the temporary integration. Be aware that deleting the integration will also remove its integration logs and rejected events.

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 integrations, the events are stored in files with the following format: 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
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.

required
object (S3 Parameters)

Configuration parameters for upload to amazon s3.

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
Example

Create a webhook integration

{
  • "id": "erp-netsuite-integration-002",
  • "integration_type": "permanent",
  • "starts_at": "2019-01-17T12:00:00Z",
  • "callback_parameters": {}
}

Response samples

Content type
application/json
{
  • "id": "sap-integration-001",
  • "status": "running",
  • "integration_type": "temporary",
  • "starts_at": "2019-01-17T12:00:00Z",
  • "ends_at": "2019-02-21T23:59:00Z",
  • "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:00Z",
  • "ends_at": "2019-02-21T23:59:00Z",
  • "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:00Z",
  • "ends_at": "2019-02-21T23:59:00Z",
  • "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"
}