Events delivery

Edit online

Events can be delivered through IBM® Cloud Object Storage and webhooks. Understand the prerequisites and procedures that are required for configuring the events.

Integrating with IBM Cloud Object Storage

If you want to use IBM Cloud Object Storage, complete the following prerequisites:
  • Create an IBM Cloud Object Storage account to use as an endpoint. To create an IBM Cloud Object Storage account, see IBM Cloud Object Storage.
    Ensure that you subscribe to a plan that fits your requirements.
    Note: Each event can be roughly 1.5 KB. A file can contain up to 1000 events or roughly 1.5 MB in file size. Use this estimate to determine how much space is needed in the IBM Cloud Object Storage.
  • Create IBM Cloud Object Storage buckets. It is recommended that you adhere to the following guidelines:
    • Create one bucket for each tenant or one bucket for each event. If you choose to use one bucket, provide a prefix for each event type.
    • The bucket names must be unique. It is recommended that you use the following naming convention for buckets:

      <tenant name>-events-<environment>-<event type>

      For example, tenant1-events-dev-1-availability-change

    • The bucket names must begin and end with lowercase alphanumeric characters, and can contain 3 - 63 characters.
  • Learn how to download events from the buckets. For more information, see Moving data from Cloud Object Storage to File or Block Storage.
  • For each event that needs to be subscribed, collect the following information and provide in IBM support case asking to setup a IBM Cloud Storage Endpoint and configure event subscriptions:
    • Bucket name for each event
    • Service API key
    • (Optional) Prefix for object names. For example, event type.
    • Inventory Visibility tenant ID
    • Event name
    • Public endpoint URL
Note: To find your public endpoint URL, complete the following steps:
  1. Go to the list of your buckets, and select the bucket name.
  2. Click the Configuration tab, and scroll down to Regular Endpoints.
  3. Under public, the public endpoint URL is present in the following format:
    s3.<region>.cloud-object-storage.appdomain.cloud
    For example, s3.us-east.cloud-object-storage.appdomain.cloud.
A file can contain up to 1000 events, but IBM does not automatically provide a count of how many events are recorded in the file. However, IBM contains the cloud-storage-tools utility utility that can complete the following tasks:
  • Retrieve the files in a Cloud Object Storage bucket.
  • Download the files locally.
  • Count the number of events in the files.
  • Delete all files from the Cloud Object Storage bucket.

To obtain this utility, open a case with IBM support and request access to the cloud-storage-tools utility.

The IBM Cloud Object Storage naming convention is {optional prefix}/{timestamp}/COS-EVENTS-{endpointId}-{timestamp}.

Integrating with webhooks

Ensure that you complete the following prerequisites for configuring webhooks. For each event that needs to be configured, provide the following details in the IBM support case requesting to setup a webhook endpoint and configure event subscriptions:
  • Inventory Visibility tenant ID
  • Event name
  • Event delivery URL: A URL where webhook events would be posted (must be an HTTPS URL).
  • Access token URL: A URL where oauth2 tokens are made available (must be an HTTPS URL).
  • Client ID: OAuth2 client ID: Credentials to authenticate webhook.
  • Client secret: OAuth2 client secret: Credentials to authenticate webhook.
  • Token duration in hours.

IBM Support takes approximately two weeks to revert with the necessary information. For more information about how to open a case with IBM Support, see Contacting IBM Support.

Webhook configuration guidelines

Other important webhook configuration guidelines include:
  • You must implement webhooks with Oauth2 client credentials grant type authentication flow.

    The instructions for OAuth2 request is same as Retrieving a token. The only difference is that you host the OAuth2 server and IBM makes token requests to the server by using the credentials that you provide.

  • Ensure that the SSL certificates for both URLs is root CA signed certificates. By default, IBM trusts the certificates that are provided by OpenJDK 11.
  • The HTTPS port that is supported for outbound calls from IBM is only 443. IBM does not support any custom port specification for allowlisting.
  • IBM does not support mTLS.
  • If your security policy requires allowlisting incoming IBM Prerequisite Scanner, contact IBM support to get the IBM Prerequisite Scanner allowlisted.
  • The webhook implementation must return 200 as a response code.
  • In the advent of authentication and authorization failures, the webhook implementation must throw standard response codes such as 401 or 403.
  • The webhook configuration on your gateway must allow for sufficient size to accommodate the payload (1 MB is a good reference).
  • It is recommended that the generated access tokens against the webhook must be valid for at least 1 hour.

Event Processing

To retrieve events, follow these best practices.
  • To improve the consumption processing performance of a COS file, IBM aggregates one or more event JSON into a single COS file. The event JSON within the COS file are separated by a "\n" new line character.
  • The introduction of the new line character between JSON objects enable the consumer to partially read the COS file. For example, iterate and reach 50 lines each time and parse JSON blocks into JSON object individually. On the other hand, if the COS file is a large JSON, the consumer system needs to parse the entire file. This has an increase risk of failure and more difficult for replay strategy in the event of an error.

    The following sample code snippet illustrates the COS file. For readability, an additional new line is added between events.

    {"eventbatch":[{"channel":"Order Management","identifiers":[],"events":[{"code":"supplyChange","timestamp":"2020-01-18T06:00:00.021Z","attributes":[{"name":"tenantId","type":"String","value":"tenant1"},{"name":"productID","type":"String","value":"SKU1024"},{"name":"unitOfMeasure","type":"String","value":"EACH"},{"name":"productClass","type":"String","value":"NEW"},{"name":"shipNode","type":"String","value":"Matrix-Store-001"},{"name":"shipByDate","type":"dateTime","value":"2500-01-01T00:00:00.000Z"},{"name":"lineReference","type":"String","value":""},{"name":"reference","type":"String","value":""},{"name":"referenceType","type":"String","value":""},{"name":"segment","type":"String","value":""},{"name":"segmentType","type":"String","value":""},{"name":"quantity","type":"Number","value":"1.0"},{"name":"changedQuantity","type":"Number","value":"1.0"},{"name":"type","type":"String","value":"ONHAND_BACKROOM_01"},{"name":"baseType","type":"String","value":"ONHAND"},{"name":"tagNumber","type":"String","value":"|||"},{"name":"updatedTs","type":"dateTime","value":"IGNORE_VALUE"},{"name":"eta","type":"dateTime","value":"1900-01-01T00:00:00.000Z"},{"name":"adjustmentReason","type":"String","value":"ADJUSTMENT"}]},{"code":"supplyChange","timestamp":"2020-01-03T15:48:02Z","attributes":[{"name":"tenantId","value":"tenant1","type":"String"},{"name":"productID","value":"SKU1024","type":"String"},{"name":"unitOfMeasure","value":"EACH","type":"String"},{"name":"productClass","value":"NEW","type":"String"},{"name":"lineReference","value":" ","type":"String"},{"name":"shipNode","value":"Matrix-Store-002","type":"String"},{"name":"shipByDate","value":"2500-01-01T00:00:00Z","type":"dateTime"},{"name":"reference","value":" ","type":"String"},{"name":"referenceType","value":" ","type":"String"},{"name":"quantity","value":"200.0","type":"Number"},{"name":"segment","value":" ","type":"String"},{"name":"segmentType","value":" ","type":"String"},{"name":"type","type":"String","value":"ONHAND_BACKROOM_01"},{"name":"baseType","type":"String","value":"ONHAND"},{"name":"tagNumber","type":"String","value":"|||"},{"name":"updatedTs","value":"2020-01-03T15:47:48Z","type":"dateTime"},{"name":"eta","value":"1900-01-01T00:00:00Z","type":"dateTime"},{"name":"adjustmentReason","type":"String","value":"ADJUSTMENT"}]}]}]}

{"eventbatch":[{"channel":"Order Management","identifiers":[],"events":[{"code":"supplyChange","timestamp":"2020-01-18T06:00:00.021Z","attributes":[{"name":"tenantId","type":"String","value":"tenant1"},{"name":"productID","type":"String","value":"SKU1024"},{"name":"unitOfMeasure","type":"String","value":"EACH"},{"name":"productClass","type":"String","value":"NEW"},{"name":"shipNode","type":"String","value":"Matrix-Store-001"},{"name":"shipByDate","type":"dateTime","value":"2500-01-01T00:00:00.000Z"},{"name":"lineReference","type":"String","value":""},{"name":"reference","type":"String","value":""},{"name":"referenceType","type":"String","value":""},{"name":"segment","type":"String","value":""},{"name":"segmentType","type":"String","value":""},{"name":"quantity","type":"Number","value":"1.0"},{"name":"changedQuantity","type":"Number","value":"1.0"},{"name":"type","type":"String","value":"ONHAND_BACKROOM_01"},{"name":"baseType","type":"String","value":"ONHAND"},{"name":"tagNumber","type":"String","value":"|||"},{"name":"updatedTs","type":"dateTime","value":"IGNORE_VALUE"},{"name":"eta","type":"dateTime","value":"1900-01-01T00:00:00.000Z"},{"name":"adjustmentReason","type":"String","value":"ADJUSTMENT"}]},{"code":"supplyChange","timestamp":"2020-01-03T15:48:02Z","attributes":[{"name":"tenantId","value":"tenant1","type":"String"},{"name":"productID","value":"SKU1024","type":"String"},{"name":"unitOfMeasure","value":"EACH","type":"String"},{"name":"productClass","value":"NEW","type":"String"},{"name":"lineReference","value":" ","type":"String"},{"name":"shipNode","value":"Matrix-Store-002","type":"String"},{"name":"shipByDate","value":"2500-01-01T00:00:00Z","type":"dateTime"},{"name":"reference","value":" ","type":"String"},{"name":"referenceType","value":" ","type":"String"},{"name":"quantity","value":"200.0","type":"Number"},{"name":"segment","value":" ","type":"String"},{"name":"segmentType","value":" ","type":"String"},{"name":"type","type":"String","value":"ONHAND_BACKROOM_01"},{"name":"baseType","type":"String","value":"ONHAND"},{"name":"tagNumber","type":"String","value":"|||"},{"name":"updatedTs","value":"2020-01-03T15:47:48Z","type":"dateTime"},{"name":"eta","value":"1900-01-01T00:00:00Z","type":"dateTime"},{"name":"adjustmentReason","type":"String","value":"ADJUSTMENT"}]}]}]}

{"eventbatch":[{"channel":"Order Management","identifiers":[],"events":[{"code":"supplyChange","timestamp":"2020-01-18T06:00:00.021Z","attributes":[{"name":"tenantId","type":"String","value":"tenant1"},{"name":"productID","type":"String","value":"SKU1024"},{"name":"unitOfMeasure","type":"String","value":"EACH"},{"name":"productClass","type":"String","value":"NEW"},{"name":"shipNode","type":"String","value":"Matrix-Store-001"},{"name":"shipByDate","type":"dateTime","value":"2500-01-01T00:00:00.000Z"},{"name":"lineReference","type":"String","value":""},{"name":"reference","type":"String","value":""},{"name":"referenceType","type":"String","value":""},{"name":"segment","type":"String","value":""},{"name":"segmentType","type":"String","value":""},{"name":"quantity","type":"Number","value":"1.0"},{"name":"changedQuantity","type":"Number","value":"1.0"},{"name":"type","type":"String","value":"ONHAND_BACKROOM_01"},{"name":"baseType","type":"String","value":"ONHAND"},{"name":"tagNumber","type":"String","value":"|||"},{"name":"updatedTs","type":"dateTime","value":"IGNORE_VALUE"},{"name":"eta","type":"dateTime","value":"1900-01-01T00:00:00.000Z"},{"name":"adjustmentReason","type":"String","value":"ADJUSTMENT"}]},{"code":"supplyChange","timestamp":"2020-01-03T15:48:02Z","attributes":[{"name":"tenantId","value":"tenant1","type":"String"},{"name":"productID","value":"SKU1024","type":"String"},{"name":"unitOfMeasure","value":"EACH","type":"String"},{"name":"productClass","value":"NEW","type":"String"},{"name":"lineReference","value":" ","type":"String"},{"name":"shipNode","value":"Matrix-Store-002","type":"String"},{"name":"shipByDate","value":"2500-01-01T00:00:00Z","type":"dateTime"},{"name":"reference","value":" ","type":"String"},{"name":"referenceType","value":" ","type":"String"},{"name":"quantity","value":"200.0","type":"Number"},{"name":"segment","value":" ","type":"String"},{"name":"segmentType","value":" ","type":"String"},{"name":"type","type":"String","value":"ONHAND_BACKROOM_01"},{"name":"baseType","type":"String","value":"ONHAND"},{"name":"tagNumber","type":"String","value":"|||"},{"name":"updatedTs","value":"2020-01-03T15:47:48Z","type":"dateTime"},{"name":"eta","value":"1900-01-01T00:00:00Z","type":"dateTime"},{"name":"adjustmentReason","type":"String","value":"ADJUSTMENT"}]}]}]}