Setup of the notification module

The second part of the setup is the installation and deployment of the notification module for commercetools. It will receive webhook calls from Stripe and make changes in commercetools' payment object.

In this document, we assume you already went through Setup of the extension module document.

Getting an notification module

You can find an image with notification module in our private registry. We recommend creating a dedicate Dockerfile extending our image with provided by you environment variable for configuration, like that:

You can find a Docker image of the notification module in our private registry. We recommend creating your own Dockerfile from our image. The notification configuration object should be injected as a build argument and turned into an environment variable. For example:

FROM registry.vuestorefront.cloud/vsf-enterprise/commercetools-stripe-integration-notification:2.0.1

ARG STRIPE_INTEGRATION_CONFIG

ENV STRIPE_INTEGRATION_CONFIG=$STRIPE_INTEGRATION_CONFIG

If you are a client of Alokai Cloud, then you can follow the steps below to deploy the notification module.

Adding a "Build commercetools Stripe integration notification" action below "Build commercetools Stripe integration extension"

build-commercetools-stripe-integration-notification:
  runs-on: ubuntu-latest
  needs: configure-deployment
  steps:
    - name: Checkout code
      uses: actions/checkout@v1
    - name: Setup node
      uses: actions/setup-node@v1
      with:
        node-version: "16.x"
    - name: Build and publish docker image
      uses: elgohr/Publish-Docker-Github-Action@master
      with:
        name: ${{ secrets.PROJECT_NAME }}-storefrontcloud-io/commercetools-stripe-integration-notification:${{ github.sha }}
        registry: ${{ secrets.DOCKER_REGISTRY_URL || 'registry.vuestorefront.cloud' }}
        username: ${{ secrets.CLOUD_USERNAME }}
        password: ${{ secrets.CLOUD_PASSWORD }}
        dockerfile: .vuestorefrontcloud/docker/commercetools-stripe-integration-notification.Dockerfile
        buildoptions: "--compress"
        buildargs: STRIPE_INTEGRATION_CONFIG
      env:
        STRIPE_INTEGRATION_CONFIG: ${{ secrets.STRIPE_INTEGRATION_CONFIG }}

Where dockerfile: .vuestorefrontcloud/docker/commercetools-stripe-integration-notification.Dockerfile specifies a path to the Dockerfile example presented above.

Extend "Deploy middleware..." step in "deploy" job

Add a new object to the apps array inside payload of your request to the Farmer. This makes Farmer deploy the given image under the dedicated path. Modify:

- name: Deploy middleware on ${{ secrets.PROJECT_NAME }}.${{ secrets.CLOUD_REGION }}.gcp.storefrontcloud.io/api/
  run: |
    if curl -f -s -H 'X-User-Id: ${{ secrets.CLOUD_USERNAME }}' -H 'X-Api-Key: ${{ secrets.CLOUD_PASSWORD }}' -H 'Content-Type: application/json' -X PATCH -d '{
      "front_version":"${{ github.sha }}",
      "additional_apps": {
        "apps":[
          {
            "name":"middleware",
            "tag":"${{ github.sha }}",
            "image":"${{ secrets.DOCKER_REGISTRY_URL || 'registry.vuestorefront.cloud' }}/${{ secrets.PROJECT_NAME }}-storefrontcloud-io/vue-storefront-middleware",
            "path":"/api/",
            "port":"8181",
            "has_base_path":false
          },
          {
            "name":"commercetools-stripe-integration-extension",
            "tag":"${{ github.sha }}",
            "image":"${{ secrets.DOCKER_REGISTRY_URL || 'registry.vuestorefront.cloud' }}/${{ secrets.PROJECT_NAME }}-storefrontcloud-io/commercetools-stripe-integration-extension",
            "path":"/commercetools-stripe-integration-extension/",
            "port":"8080",
            "has_base_path":false
          }
        ],
        "enabled": true
      }
    }' ${{ secrets.CLOUD_API_BASE_URL || 'https://farmer.vuestorefront.cloud' }}/instance/${{ secrets.PROJECT_NAME }}-${{ secrets.CLOUD_REGION }}-gcp-storefrontcloud-io; then
      echo "Instance updated"
    else
      echo "Something went wrong during the update process..."
      exit 1
    fi

To the:

- name: Deploy middleware on ${{ secrets.PROJECT_NAME }}.${{ secrets.CLOUD_REGION }}.gcp.storefrontcloud.io/api/
  run: |
    if curl -f -s -H 'X-User-Id: ${{ secrets.CLOUD_USERNAME }}' -H 'X-Api-Key: ${{ secrets.CLOUD_PASSWORD }}' -H 'Content-Type: application/json' -X PATCH -d '{
      "front_version":"${{ github.sha }}",
      "additional_apps": {
        "apps":[
          {
            "name":"middleware",
            "tag":"${{ github.sha }}",
            "image":"${{ secrets.DOCKER_REGISTRY_URL || 'registry.vuestorefront.cloud' }}/${{ secrets.PROJECT_NAME }}-storefrontcloud-io/vue-storefront-middleware",
            "path":"/api/",
            "port":"8181",
            "has_base_path":false
          },
          {
            "name":"commercetools-stripe-integration-extension",
            "tag":"${{ github.sha }}",
            "image":"${{ secrets.DOCKER_REGISTRY_URL || 'registry.vuestorefront.cloud' }}/${{ secrets.PROJECT_NAME }}-storefrontcloud-io/commercetools-stripe-integration-extension",
            "path":"/commercetools-stripe-integration-extension/",
            "port":"8080",
            "has_base_path":false
          },
          {
            "name":"commercetools-stripe-integration-notification",
            "tag":"${{ github.sha }}",
            "image":"${{ secrets.DOCKER_REGISTRY_URL || 'registry.vuestorefront.cloud' }}/${{ secrets.PROJECT_NAME }}-storefrontcloud-io/commercetools-stripe-integration-notification",
            "path":"/commercetools-stripe-integration-notification/",
            "port":"8080",
            "has_base_path":false
          }
        ],
        "enabled": true
      }
    }' ${{ secrets.CLOUD_API_BASE_URL || 'https://farmer.vuestorefront.cloud' }}/instance/${{ secrets.PROJECT_NAME }}-${{ secrets.CLOUD_REGION }}-gcp-storefrontcloud-io; then
      echo "Instance updated"
    else
      echo "Something went wrong during the update process..."
      exit 1
    fi

Make sure to set STRIPE_INTEGRATION_CONFIG secret in your repository if you follow the workflow setup. You can learn about its content in the environment variables section.

Make sure your Fusion Auth user has permissions to vsf-enterprise namespace (instances array). Otherwise, you will get a HTTP 401 Code.

Register a webhook in Stripe dashboard

Let's open Webhooks view in the Stripe dashboard and register a webhook endpoint. In order to do that:

Click "+ Add endpoint" button.
Endpoint URL should match pattern like https://<YOUR_STOREFRONT_URL>/commercetools-stripe-integration-notification/<YOUR_PROFILE_NAME>.

For example, for the storefront under URL https://storefront-vyhi5b8f.europe-west1.gcp.storefrontcloud.io/ and STRIPE_INTEGRATION_CONFIG containing:

{
  "stripe": {
    "stripeProfile1": {
      "secretKey": "sk_test_***"
    }
  },
}

It would be equal to https://storefront-vyhi5b8f.europe-west1.gcp.storefrontcloud.io/commercetools-stripe-integration-notification/stripeProfile1.

Then select the 2022-11-15 Version since the notification module has been developed using that one (the oldset supported API version is 2020-08-27),
Then add new events by clicking "+ Select events" button and select: payment_intent.payment_failed, payment_intent.succeeded, charge.refunded, charge.succeeded.
Submit by clicking "Add endpoint" button.
Then you are on the created webhook's view - here, find the "Signing secret" column and click "Reveal". A key starting with whsec_ will appear - copy it, as we will need it in the next step.

Environment variables

There is one mandatory environment variable called STRIPE_INTEGRATION_CONFIG. It contains settings as attributes in a JSON structure:

{
  "commercetools": {
    "commercetoolsProjectKey1": {
      "clientId": "xxx",
      "clientSecret": "xxx",
      "apiHost": "xxx",
      "authHost": "xxx",
      "scopes": ["manage_payments:commercetoolsProjectKey1"]
    },
    "commercetoolsProjectKey2": {
      "clientId": "xxx",
      "clientSecret": "xxx",
      "apiHost": "xxx",
      "authHost": "xxx",
      "scopes": ["manage_payments:commercetoolsProjectKey2"]
    }
  },
  "stripe": {
    "stripeProfile1": {
      "secretKey": "sk_test_xxx",
      "endpointSecret": "whsec_xxx"
    }
  },
  "logLevel": 20,
  "maxRetry": 2
}

STRIPE_INTEGRATION_CONFIG JSON structure contains different attribute groups as described below:

commercetools attribute group: Multiple child attributes can be provided in the commercetools attribute. Each direct child attribute must representant a commercetools project, the module requires only manage_payments scope,
stripe attribute group: Multiple child attributes can be provided in the stripe attribute. Each direct child attribute must representant a Stripe merchant account,
other attribute group: Attributes in this group can be set as direct child attributes in the root of the JSON.

Preparing the credentials

For test environment create a test account, then you will be able to find them here,
For live environment follow the official Stripe documentation.

Required attributes

Group	Name	Content
`commercetools`	`clientId`	API client's clientId
`commercetools`	`clientSecret`	API client's clientSecret
`commercetools`	`apiHost`	API host
`commercetools`	`authHost`	Auth host
`commercetools`	`scopes`	API client's scopes
`stripe`	`secretKey`	You'll be making API requests that are authenticated with an Stripe secret key.
`stripe`	`endpointSecret`	If you are testing your webhook locally with the Stripe CLI you can find the endpoint's secret by running `stripe listen`. Otherwise, find your endpoint's secret in your webhook settings in the Developer Dashboard. It starts with `whsec_` (copied in the previois step)

Optional attributes

Group	Name	Content	Default value
other	`logLevel`	The log level. Here you can find list of available options.	`"info"`
other	`maxRetry`	Maximum amount of retries if commercetools responds with 409 status code	2

Optional environment variables

PORT - tells on what port application will listen. By default, it equals 8081.

Running

If you want to run it locally, you can use the sample Dockerfile created in the "Getting an notification module" guide.

Make sure to provide the required STRIPE_INTEGRATION_CONFIG environment variable.

Main difference when compared to the extension module

The application listens on port 8081 by default. It requires providing Stripe profile as a param in the URL. So if you hit http://localhost:8081/stripeProfile1 with the request, then the module will look for the configuration of stripe.stripeProfile1.

Testing locally

We recommend using the Stripe CLI in order to test the notification module locally.

Example usage of Stripe CLI for the notification module listening on localhost:8081, and we want to use stripeProfile1:

stripe listen --forward-to localhost:8081/stripeProfile1