Overview

Infosys Equinox App Marketplace allows apps to register for asynchronous webhooks (for any of the events on the platform), and apps can register for pre-defined scopes (microservices and associated roles) to call back Infosys Equinox Microservices APIs.

Asynchronous Webhooks

Webhooks notify applications when specific events occur on Infosys Equinox Microservices. Apps can register for webhooks to get notified about the events (async) occurring on the platform.

Step 1: Webhook Configuration

Here is the sample webhook configuration:

Note: Apps can be configured for multiple webhooks. There is no restriction on the number of webhooks that can be configured for an app.

 "webhooksConfig": [
                {
                    "url": "https://sampleurl.com/callback",
                    "webhookType": "ASYNC",
                    "priority": "Normal",
                    "events": [
                        "catalogservice/product/create"
                    ]
                }

Step 2:  Validate Signature

Once the app has registered for async webhooks, it will be notified when events occur on the platform. To view the event payload, the app has to perform signature verification. Below are the steps to fetch the app secret stored for the app and use it to generate the signature for the payload received:

1. Fetch the app secret for the app ID, which is included in the payload.
2. Generate the signature using the calculateHMACSHA256 function. It takes the event payload and app secret as parameters.
3. The verifySignature function validates the signature received in the payload header against the generated signature.
4. If there is a mismatch, it returns an authentication failure response.

Functions included – CommonUtils

1. verifySignature(event, signatureReceived, apiSecret)
2. calculateHMACSHA256(event, secretKey) 

App Callback

Step 1: Configure for the App Scopes

Identify the callbacks (that are required from the app) to be updated to Equinox APIs and configure them as app scopes in the app for generating callback access tokens. Provide the link to the list of app scopes on the platform.

Step 2: Get Access Token for Callback

For getting the auth token via Authorize Lambda:

• Things Third-Party App should know:

1. 1. Authorize Lambda Endpoint
   2. App ID
   3. App Version
   4. Store ID ( on which App is installed)
   5. Base URL of the App
   6. State and Nonce (optional)
   7. expiryTime (should be 5 seconds after the current time)

• Request to Authorize Lambda should have the following:
  Header: signature (requestBody encoded with the app secret)
  Request Body:

{
    "storeId": "11",
    "appId": "653906ec170e703d543dbf3f",
    "appVersion": "8.16.0",
    "baseUrl": "https: //8jr9vvcqgi.execute-api.us-east-1.amazonaws.com",
    "expireTime": 1699260660745,
    "nonce": "nonce",
    "state": "state"
}

• Required Step: to get the app secret, copy the app secret manually or subscribe for webhooks:

{
    "entity": "app",
    "url": "domain/appSecretEventListener",
    "webhookType": "ASYNC",
    "events": [
        "appmarketplaceservices/generateapikeyandsecret/create"
    ]
}

2. To get the store ID when the app is installed in the store, subscribe to webhooks:

{
    "entity": "app",
    "url": "doamin/appInstallationListener",
    "webhookType": "ASYNC",
    "events": [
        "appmarketplaceservices/apps/updateinstallation"
    ]
}

3. Call Authorize Lambda with:
   Header: signature (requestBody encoded with the app secret)
   Request Body:

{
    "storeId": "",
    "appId": "",
    "appVersion": "",
    "baseUrl": "",
    "expireTime":"",
    "nonce": "",
    "state": ""
}

Reference

The following diagram depicts the asynchronous webhooks workflow of App Marketplace: Note: For the list of events and its payload of all microservices, see Events and its Payload.

Webhooks Payload Verification

A signature is a response generated when the payload body is encoded with the App Secret Key.

Prerequisite

Serverless apps should store their app secret, generated when the app is created in the Infosys Equinox App Marketplace.

Action

1. Receive the signature: Check if you received a signature in the header section or not. The non-availability of the signature means the app secret is not present for that app.

2. Extract signature and data: If the signature is present when the receiver receives the webhook data, extract both the data from the body and the received signature from the headers.

3. Calculate the signature: Use the calculate HMACSHA256 function to calculate the signature based on the received data and the app secret key.

4. Compare the Signature: Compare the received signature with the calculated signature. If they match, the data is not tampered with, and the sender is verified.

The following table describes the sample payload and code snippet:

Appendix

List of Events in All Microservices

Refer to the list of all the events on the platform available across microservices:

• Events – Accounts
• Events – App Marketplace
• Events – Address
• Events – Authorization
• Events – Cart
• Events – Catalog
• Events – Customers (User)
• Events – Feed Job
• Events – Feeds
• Events – Foundation
• Events – Inventory
• Events – Lists
• Events – Location
• Events – Loyalty
• Events – Merchandising
• Events – Notification
• Events – Order
• Events – Payment
• Events – Pricing
• Events – Promotions
• Events – Ratings and Reviews
• Events – Reporting
• Events – Search
• Events – Shipping
• Events – Storefront Orchestration
• Events – Subscription
• Events – Tax

Revision History
2024-05-20 | JP – Created the page and added the content.