Events

Retrieving all subscriptions

get

Retrieves all events with associated subscription details.

Note: Events that have no past subscription information will contain empty metadata. Fields that are referenced in the 'excludedFields' array will be filtered out from the event payload. The absence of a field in 'excludedFields' means it will be automatically included in the event payload.

Required scopes

This endpoint requires the following scopes:

• : Needed to read subscriptions.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Header parameters

Accept-LanguagestringOptional

List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields. The specified languages need to be defined in the Configuration Service under project_lang key. Otherwise they will be ignored.

Note: If not specified, localized fields will be retrieved in the default language configured by the tenant in the Configuration Service.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7

Responses

200

The request was successful. An event catalog with associated subscription details is returned.

application/json

Details of the event subscription.

subscriptionstring · enumOptional

Status of the subscription.

Possible values:

excludedFieldsstring[]Optional

If subscription is of type SUBSCRIBED, excludedFields will contain the list of keys from the "event.eventSchema" that the user has previously unsubscribed from. Note: Only root level fields are supported.

400

Request was syntactically incorrect. Details are provided in the response payload.

application/json

401

Unauthorized

application/json

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

application/json

404

The requested resource does not exist.

application/json

500

Some server-side error occurred. Details are provided in the response payload.

application/json

get/webhook/{tenant}/event-subscriptions

GET /webhook/{tenant}/event-subscriptions HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "event": {
      "type": "product.updated",
      "eventSchema": {
        "id": "String",
        "name": "LocalizedString",
        "description": "LocalizedString",
        "productType": "String"
      },
      "name": {
        "en": "Updated"
      },
      "group": {
        "en": "Product"
      },
      "description": {
        "en": "The event is emitted when a product is being updated."
      }
    },
    "metadata": {
      "version": 1,
      "createdAt": "2022-03-31T13:13:25.816Z",
      "modifiedAt": "2022-03-31T13:13:25.816Z"
    },
    "subscription": "SUBSCRIBED",
    "excludedFields": [
      "description"
    ]
  }
]

Subscribing and unsubscribing from events

patch

Updates the list of subscriptions by either subscribing to or unsubscribing from specified events.

To receive events with fewer fields, you can specify the names of fields that you want to exclude in the 'fieldsToUnsubscribe' array. To re-include the previously excluded fields, you can provide their names in the 'fieldsToSubscribe' array.

Required scopes

This endpoint requires the following scopes:

• : Needed to manage subscriptions.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Bodyobject · Webhook subscription update item[]

Subscription changes.

eventTypestringRequired

Unique identifier of the event.

Example: product.updated

actionstring · enumOptional

Indicates whether the event should be subscribed to or unsubscribed from.

Possible values:

fieldsToUnsubscribestring[]Optional

Fields to exclude from notification.

fieldsToSubscribestring[]Optional

Fields to re-include in the notification. To be used when user wants to subscribe to previously unsubscribed fields.

Responses

207

Multi Status response containing individual results for each subscription request.

application/json

Object containing the result of event subscription.

eventTypestringOptional

codeintegerOptional

statusstringOptional

messagestringOptional

400

Request was syntactically incorrect. Details are provided in the response payload.

application/json

401

Unauthorized

application/json

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

application/json

404

The requested resource does not exist.

application/json

409

Conflict. Returned when creating a webhook configuration for a type that is already configured, or when a legacy event-type PATCH path is used while multiple eventsConfiguration entries exist for that event type.

application/json

500

Some server-side error occurred. Details are provided in the response payload.

application/json

patch/webhook/{tenant}/event-subscriptions

PATCH /webhook/{tenant}/event-subscriptions HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 226

[
  {
    "eventType": "product.created",
    "action": "SUBSCRIBE",
    "fieldsToSubscribe": [
      "name"
    ],
    "fieldsToUnsubscribe": [
      "description"
    ],
    "metadata": {
      "version": 1
    }
  },
  {
    "eventType": "product.updated",
    "action": "UNSUBSCRIBE",
    "metadata": {
      "version": 2
    }
  }
]

[
  {
    "eventType": "product.created",
    "code": 200,
    "status": "OK"
  },
  {
    "eventType": "product.updated",
    "code": 200,
    "status": "OK"
  },
  {
    "eventType": "product.deleted",
    "code": 409,
    "status": "CONFLICT",
    "message": "Unique constraint violation for provided eventType and metadata version. It is possible to update an eventsubscription only by always providing the latest version. Fetch the event subscriptions to get the latest version."
  }
]