DX Engine Listener

A DX Engine Listener is an endpoint that can receive any webservice request (e.g. from a third-party webhook) and convert that into a normal DX Engine request.

Listeners are specific to an environment. When a Listener is first created, it is assigned a Listener UUID (universally-unique identifier) that cannot be changed and a Listener Locator (a hex value) that uniquely identifies the customer and environment to which the Listener belongs.

If a Listener is copied to another environment, the copied listener in the target environment receives a new globally-unique identifier that cannot be changed.

Once a Listener is configured, it is accessible at:

{DX Engine URL}/api/experience/_listener/:listenerLocator/:listenerUuid

API

Create a Listener

POST /api/listeners

POST {{DX_ENGINE_URL}}/api/listeners
content-type: application/json
Authorization: Bearer {{DX_ENGINE_SYSTEM_TOKEN}}
X-Customer-Code: {{customerCode}}

{
  "listener": {
    "listenerCode": "remove-product",
    "name": "Remove Product",
    "sync": true,
    "endpointRequestSpec": {
      "methods": ["POST", "PUT"]
    },
    "engineRequest": {
      "templateCode": "test-incoming",
      "context": {
        "productId": "`body.productId`"
      }
    },
    "endpointResponse": {
      "status": 200,
      "body": {
        "testOne": "`engineResponse.components['test-one']`",
        "incomingMethod": "`requestMethod`"
      },
      "headers": [
        {
          "header": "content-type",
          "value": "application/json"
        },
        {
          "header": "x-remekie",
          "value": "Hugo"
        }
      ]
    }
  }
}

Response:

{
    "message": "Successfully created Listener",
    "listener": {
        "listenerCode": "remove-product",
        "name": "Remove Product",
        "sync": true,
        "endpointRequestSpec": {
            "methods": [
                "POST",
                "PUT"
            ]
        },
        "engineRequest": {
            "templateCode": "test-incoming",
            "context": {
                "productId": "`body.productId`"
            }
        },
        "endpointResponse": {
            "status": 200,
            "body": {
                "testOne": "`engineResponse.components['test-one']`",
                "incomingMethod": "`requestMethod`"
            },
            "headers": [
                {
                    "header": "content-type",
                    "value": "application/json"
                },
                {
                    "header": "x-remekie",
                    "value": "Hugo"
                }
            ]
        },
        "@listenerUuid": "8515ef2e-530d-4d6e-9754-7b1bfbbbc92d",
        "@listenerPath": "6875676f:70726576696577/8515ef2e-530d-4d6e-9754-7b1bfbbbc92d"
    }
}

Take note of the generated Listener UUID (@listenerUuid) and Listener Path (@listenerPath) in the response. The Listener Path a combination of the Listener Locator and the Listener UUID and is formed :listenerLocator/:listenerUuid.

The URL path to the Listener in this example is: {DX Engine URL}/api/experience/_listener/76875676f:70726576696577/8515ef2e-530d-4d6e-9754-7b1bfbbbc92d

Update a Listener

PATCH /api/listeners/:listenerCode

PATCH {{DX_ENGINE_URL}}/api/listeners
content-type: application/json
Authorization: Bearer {{DX_ENGINE_SYSTEM_TOKEN}}
X-Customer-Code: {{customerCode}}

{
  "listener": {
    "name": "Remove Product",
    "description": "Removes the product from the SFCC catalog based on the incoming trigger from Slack",
    "sync": true,
    "endpointRequestSpec": {
      "methods": ["POST", "PUT"]
    },
    "engineRequest": {
      "templateCode": "test-incoming",
      "context": {
        "productId": "`body.productId`"
      }
    },
    "endpointResponse": {
      "status": 200,
      "body": {
        "testOne": "`engineResponse.components['test-one']`",
        "incomingMethod": "`requestMethod`"
      },
      "headers": [
        {
          "header": "content-type",
          "value": "application/json"
        },
        {
          "header": "x-remekie",
          "value": "Hugo"
        }
      ]
    }
  }
}

Response:

{
    "message": "Successfully updated Listener"
}

List all Listeners

GET /api/listeners

GET {{DX_ENGINE_URL}}/listeners
content-type: application/json
Authorization: Bearer {{DX_ENGINE_SYSTEM_TOKEN}}
X-Customer-Code: {{customerCode}}

Response:

[
  {
    "name": "Remove Product",
    "sync": true,
    "endpointRequestSpec": {
      "methods": [
        "POST",
        "PUT"
      ]
    },
    "engineRequest": {
      "templateCode": "test-incoming",
      "context": {
        "productId": "`body.productId`"
      }
    },
    "endpointResponse": {
      "status": 200,
      "body": {
        "testOne": "`engineResponse.components['test-one']`",
        "incomingMethod": "`requestMethod`"
      },
      "headers": [
        {
          "header": "content-type",
          "value": "application/json"
        },
        {
          "header": "x-remekie",
          "value": "Hugo"
        }
      ]
    },
    "listenerCode": "remove-product",
    "@listenerUuid": "8515ef2e-530d-4d6e-9754-7b1bfbbbc92d",
    "@listenerPath": "6875676f:70726576696577/8515ef2e-530d-4d6e-9754-7b1bfbbbc92d"
  }
]

Get a Specific Listener

GET /api/listeners/:listenerCode

GET {{DX_ENGINE_URL}}/api/listeners/remove-product
content-type: application/json
Authorization: Bearer {{DX_ENGINE_SYSTEM_TOKEN}}
X-Customer-Code: {{customerCode}}

Remove a Listener

DELETE /api/listeners/:listenerCode

DELETE {{DX_ENGINE_URL}}/api/listeners/remove-product
content-type: application/json
Authorization: Bearer {{DX_ENGINE_SYSTEM_TOKEN}}
X-Customer-Code: {{customerCode}}

Response:

{
    "message": "Successfully deleted Listener"
}

Listener Configuration details

• sync is optional and will default to false. false means that the incoming request will not wait for the Engine to complete processing the given Template and will respond immediately with a request ID that can be used later to lookup the response. true means the incoming request will wait for the Engine to complete processing the given Template and respond with the Engine's results (which, if specified, will be altered by endpointResponse)
• endpointRequestSpec is mandatory.
  • methods is the list of methods that this listener will respond to. At least one must be specified.
• engineRequest is mandatory
• engineRequest.templateCode is mandatory and can be an expression
• engineRequest.context is an optional object where each node can be an expression. If not specified, the body of the incoming request will be used. If the body is undefined, an empty object will be used as the context.
• engineRequest block has access to:
  • headers - From the incoming API request
  • method - From the incoming API request
  • query - From the incoming API request
  • body - From the incoming API request
• endpointResponse is optional. If not specified, the normal engine response is returned by the listener. If specified, status, body and headers must be specified.
• endpointResponse block has access to:
  • requestHeaders - From the incoming API request
  • requestMethod - From the incoming API request
  • requestQuery - From the incoming API request
  • requestBody - From the incoming API request
  • engineResponse - response from the engine
• When the Listener is first created, it is assigned a globally-unique identifier that cannot be changed.