Cloud Event Notification Services

Cloud Event Notification services offer an alternative to webhooks for receiving event messages. There are two cloud services to configure with your Kibo application.

1. Google Cloud Platform
2. AWS EventBridge

Google Cloud Platform

This section explains how to configure Google Cloud Platform (GCP) with the Kibo application. 

Prerequisites

To configure GCP, you must have the following:

• GCP Account: Ensure you have an active Google Cloud Platform (GCP) account.
• GCP Pub/Sub Topic: Create a Pub/Sub topic for handling event notifications.

Set Up GCP Pub/Sub Topic

To create a Pub/Sub topic, follow the Google Cloud instructions. Once your GCP Pub/Sub topic is created, grant publish permissions to Kibo’s Google Cloud Platform account. Use the following email to provide permissions at events@kibocommerce-public.iam.gserviceaccount.com.

Application Configuration

To configure cloud event notifications for your Kibo application, follow these steps:

1. Log in to the Kibo Dev Center.
2. Subscribe to events in the Kibo application. See the Subscribe to Events topic for more details on the subscription steps.
3. In the “URL” field, enter the URI in the following format:gcppubsub://{gcp-project-id}/{gcp-topic-id}
   • Example: gcppubsub://my-gcp-project/my-pub-sub-topic
4. Install the configured Kibo application to the desired tenant. See the Install the Application topic for more details on the installation steps.
5. Make sure you enable the installed application to activate event notifications.

Event Message Structure

The event message is an object that contains data and attributes properties.

• The data property is an object identical to the body of the webhook event as described in the Webhooks documentation.
• The attributes property is an object that matches the headers present in the Webhooks documentation. 

See this example for the event message structure:

{
    "data": {
        "eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "topic": "product.created",
        "entityId": "shoe",
        "timestamp": "2024-05-17T19:14:36.478Z",
        "correlationId": "guid",
        "isTest": false
    },
    "attributes": {
        "tenantId": "12345",
        "siteId": "1235",
        "masterCatalogId": "1",
        "catalogId": "1",
        "currencyCode": "usd",
        "priceListCode": "savings",
        "pricePlanCode": "savings",
        "purchaseLocation": "10",
        "correlationId": "guid",
        "localeCode": "en-US"
    }
}

AWS EventBridge

This section explains how to configure AWS EventBridge with the Kibo application. 

Prerequisites

To configure AWS EventBridge, you must have the following:

• AWS Account: Ensure you have an active AWS account.
• AWS Event Bus: Create an Event Bus in AWS for handling event notifications.

Set Up AWS Event Bus 

To create an AWS Event Bus follow the AWS instructions. Once your AWS Event Bus is created, grant "PutEvents" permission to Kibo’s AWS account. 

Use the following policy example to configure cross-account permissions:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "KiboCrossAccountPublish",
    "Effect": "Allow",
    "Principal": {
      "AWS": "arn:aws:iam::542216209467:root"
    },
    "Action": "events:PutEvents",
    "Resource": "arn:aws:events:us-east-1:{MY_AWS_ACCOUNT_ID}:event-bus/{MY_EVENT_BUS_NAME}"
  }]
}

Application Configuration

To configure AWS EventBridge with your Kibo application, follow these steps:

1. Log in to the Kibo Dev Center.
2. Subscribe to events in the Kibo application. See this Subscribe to Events topic for more details on the subscription steps.
3. In the “URL” field, enter the ARN in the following format: awseventbridge://{aws-event-bus-arn}.
   • For example: awseventbridge://arn:aws:events:us-east-1:123:event-bus/central-event-bus.
4. Install the configured Kibo application to the desired tenant. See Install the Application topic for more details on the installation steps.
5. Make sure you enable the installed application to activate event notifications.

Event Message Structure

The event message is an object in the AWS EventBridge structure. Refer to the AWS EventBridge documentation for more details.  The AWS EventBridge structure includes the following important fields.

• The detail-typefield matches the Kibo event topic for which the subscription was created (e.g., "product.updated").
• The source field should be "com.kibocommerce".
•  The detail property contains two objects data and attributes.
  • The data property is an object identical to the body of the webhook event as described in the Webhooks documentation.
  • The attributes property matches the headers present in the Webhooks documentation.
    

See this example for the event message structure:

{
  "detail-type": "event.topic", // This matches the Kibo topic, such as "product.updated"
  "source": "com.kibocommerce",
  "detail": {
    "data": {
      "eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "topic": "product.created",
      "entityId": "shoe",
      "timestamp": "2024-05-17T19:14:36.478Z",
      "correlationId": "guid",
      "isTest": false
    },
    "attributes": {
      "tenantId": "string",
      "siteId": "string",
      "masterCatalogId": "string",
      "catalogId": "string",
      "currencyCode": "string",
      "priceListCode": "string",
      "pricePlanCode": "string",
      "purchaseLocation": "string",
      "correlationId": "string",
      "localeCode": "string"
    }
  },
  "version": "0",
  "id": "17793124-05d4-b198-2fde-7ededc63b103",
  "account": "111122223333",
  "time": "2021-11-12T00:00:00Z",
  "region": "ca-central-1",
  "resources": [
    "arn:aws:s3:::DOC-EXAMPLE-BUCKET1"
  ]
}