Skip to main content
API docs by Redocly

Event stream API (1.0)

Download OpenAPI specification:Download

Team Partner Enablement: team-partner-enablement@newstore.com

Eventstream API

subscriptions

Subscriptions

Get information about publication attempts for a given subscription.

Get information about published events or events that failed to be published to a tenant's event stream subscriptions.

Authorizations:
oauth
path Parameters
subscription_id
required
string

Unique identifier of the subscription.

query Parameters
from
string <date-time>
Example: from=2022-12-31T23:59:59Z

Only return events which were attempted to be published after this date.

to
string <date-time>
Example: to=2023-02-01T09:12:23Z

Only return events which were attempted to be published before this date.

event_name
string
Example: event_name=order.created

The name of an event stream event.

status
string
Example: status=success

The status of the publishing attempt (either 'success' or 'failure').

domain_entity_id
string
Example: domain_entity_id=f47ac10b-58cc-4372-a567-0e02b2c3d479

The ID of a domain entity, for example an order ID.

domain_entity_type
string
Example: domain_entity_type=order

The name of a domain entity, for example 'order' or 'fulfillment_request'.

Responses

Response samples

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

Retry event publication

Will attempt to re-publish the selected publication attempt into the target system. Based on the outcome of the attempt a new entry will be posted into the event-publications showing the outcome of the action.

Authorizations:
oauth
path Parameters
publication_id
required
string

Unique identifier of the publication.

subscription_id
required
string

Unique identifier of the subscription.

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "instance": "../dictionary",
  • "request_id": "string",
  • "status": 100,
  • "title": "string",
  • "type": "about:blank"
}

List registered subscriptions

Lists all configured subscriptions.

Authorizations:
oauth

Responses

Response samples

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

Create a new subscription

Registers a new subscription. 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. The subscription will receive all events listed in the event_types property. To get a full list of available events refer to the /event-types endpoint. The created subscription will be started automatically. At most 25 subscriptions can be registered (including temporary and stopped subscriptions). 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 subscription 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 subscription is automatically stopped. You can then use the Delete subscription method to delete the temporary subscription. Be aware that deleting the subscription will also remove its logs and rejected events. In case of webhook subscription, 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 subscription, 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 subscription type can not be modified after creation.
Authorizations:
oauth
Request Body schema: application/json
id
required
string [ 1 .. 50 ] characters ^[a-z0-9-]+$

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

subscription_type
required
string
Enum: "PERMANENT" "TEMPORARY"

Type of the subscription. Temporary subscriptions can not be updated and will be stopped automatically once the last event has been sent.

notification_url
string <url>

Endpoint that will receive notifications about the subscriptions lifecycle changes.

starts_at
string <date-time>

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

ends_at
string <date-time>

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

event_types
required
Array of strings non-empty

A list of events to listen to (e.g. order.created, order.completed, return.processed). At least 1 event type is required.

required
object or object

Responses

Request samples

Content type
application/json
Example

Create a webhook subscription

{
  • "id": "webhook-subscription-123",
  • "subscription_type": "TEMPORARY",
  • "starts_at": "2024-05-01T00:00:00Z",
  • "ends_at": "2024-05-02T00:00:00Z",
  • "event_types": [
    ],
  • "parameters": {}
}

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "instance": "../dictionary",
  • "request_id": "string",
  • "status": 100,
  • "title": "string",
  • "type": "about:blank"
}

Updates the subscription

Modify the subscription. Can be used to start or stop an existing subscription.

Authorizations:
oauth
path Parameters
subscription_id
required
string

Unique identifier of the subscription.

Request Body schema: application/json
status
required
string
Enum: "RUNNING" "STOPPED" "COMPLETED" "FAILED" "INITIALIZING"

Status of the subscription. Newly added subscriptions will start automatically.

Responses

Request samples

Content type
application/json
{
  • "status": "STOPPED"
}

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "instance": "../dictionary",
  • "request_id": "string",
  • "status": 100,
  • "title": "string",
  • "type": "about:blank"
}

Get subscriptions details

Returns details about an existing subscription.

Authorizations:
oauth
path Parameters
subscription_id
required
string

Unique identifier of the subscription.

Responses

Response samples

Content type
application/json
{
  • "id": "sample-webhook-filters-123",
  • "subscription_type": "TEMPORARY",
  • "status": "INITIALIZING",
  • "starts_at": "2024-05-01T20:02:00Z",
  • "ends_at": "2024-05-02T20:02:00Z",
  • "event_types": [
    ],
  • "parameters": {}
}

Delete the subscription.

Delete an existing subscription.

Authorizations:
oauth
path Parameters
subscription_id
required
string

Unique identifier of the subscription.

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "instance": "../dictionary",
  • "request_id": "string",
  • "status": 100,
  • "title": "string",
  • "type": "about:blank"
}

Get subscription log

Return the last 50 subscription log entries.

Authorizations:
oauth
path Parameters
subscription_id
required
string

Unique identifier of the subscription.

Responses

Response samples

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

event-types

Event Types

List events that can be subscribed to.

Lists all subscribeable events.

Authorizations:
oauth

Responses

Response samples

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