Subscribe to Messages

Ask about this Page
Copy for LLM
View as Markdown
In this tutorial, you will learn how to create a Subscription in your Project. While Composable Commerce supports several Destinations, this tutorial covers three: Amazon Web Services EventBridge, Amazon Web Services Simple Queue Service (SQS), and Microsoft Azure Service Bus (ASB).

Goal

Create a Subscription that sends a notification via email to your customer when an order is created.

Prerequisites

  1. Credentials for an API Client with the Manage Subscriptions scope. If you don't have an API Client yet, create one.

  2. This tutorial covers three Destination types:

Create a Subscription

Before creating a Subscription, you need to gather some data from the destination service you are using.

Access and queue

AWS EventBridge

You need your AWS account Identifier and the region in which you want to receive the messages. When you create the Subscription, Composable Commerce automatically creates a new event source in the specified AWS account and region. You can then associate the event source with an event bus and configure forwarding rules in the AWS EventBridge console.

AWS SQS

You need an access key ID and a secret access key. To learn how, see create your own security credentials.
You also need a queue in SQS. For instructions, see create a queue and get the URL and the region of the queue.

Azure

First, create a queue in Azure Service Bus. When you create the queue, ensure that the Enable sessions checkbox is unchecked, as this option is not supported by the API.
Next, get the connection string needed to create an ASB Subscription. For instructions, see Get a Service Bus connection string.

Messages

The messages field is an array of MessageSubscriptions which require a resourceTypeId. For the full list of supported values, see MessageSubscriptionResourceTypeId.
The following code snippets show examples of passing order as resourceTypeId in different languages.

EventBridge Subscription

{
  "destination": {
    "type": "EventBridge",
    "accountId": "<my-account-id>",
    "region": "<my-region>"
  },
  "messages": [
    {
      "resourceTypeId": "order"
    }
  ]
}

If the creation was successful, you will get a response similar to the following:

{
  "changes": [],
  "createdAt": "<timestamp>",
  "destination": {
    "accountId": "<my-account-id>",
    "region": "<my-region>",
    "source": "aws.partner/commercetools.com/<project-key>/eventbridge",
    "type": "EventBridge"
  },
  "id": "<subscription-id>",
  "lastModifiedAt": "<timestamp>",
  "messages": [
    {
      "resourceTypeId": "order",
      "types": []
    }
  ],
  "version": 1
}

SQS Subscription

{
  "destination": {
    "type": "SQS",
    "queueUrl": "<url-to-my-queue>",
    "authenticationMode": "IAM",
    "region": "<my-region>"
  },
  "messages": [
    {
      "resourceTypeId": "order"
    }
  ]
}

If the creation was successful, you will get a response similar to the following:

{
  "changes": [],
  "createdAt": "<timestamp>",
  "destination": {
    "accessKey": "<my-access-key>",
    "accessSecret": "<my-access-secret>",
    "queueUrl": "<my-queue-url>",
    "region": "<my-region>",
    "type": "SQS",
    "authenticationMode": "Credentials"
  },
  "id": "<subscription-id>",
  "lastModifiedAt": "<timestamp>",
  "messages": [
    {
      "resourceTypeId": "order",
      "types": []
    }
  ],
  "version": 1
}

ASB Subscription

{
  "destination": {
    "type": "AzureServiceBus",
    "connectionString": "Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<key-name>;SharedAccessKey=<key>;EntityPath=<queue-name>"
  },
  "messages": [
    {
      "resourceTypeId": "order"
    }
  ]
}

If the creation was successful, you will get a response similar to the following:

{
  "changes": [],
  "createdAt": "<timestamp>",
  "destination": {
    "connectionString": "<my-connectionString>",
    "type": "AzureServiceBus"
  },
  "id": "<subscription-id>",
  "lastModifiedAt": "<timestamp>",
  "messages": [
    {
      "resourceTypeId": "order",
      "types": []
    }
  ],
  "version": 1
}

Receive a message using PHP and SQS

To receive a message from the queue and use its body to send a notification, you need to poll it from the queue. For the purpose of this tutorial, the following example prints the message body in the browser using PHP. You are free to use any language you prefer.

Create a PHP file with the following snippet. For the client, we use the factory method. For more details, see the SQS documentation.

$client = SqsClient::factory(array(
    'profile' => '<my-profile>',
    'region'  => '<my-region>'
));

$result = $client->receiveMessage(array(
    'QueueUrl' => <my-queue-url>,
));

foreach ($result->getPath('Messages/*/Body') as $messageBody) {
    // Do something with the message
    echo $messageBody;
}

When you run this code, and if you have a message in your queue, you will see its body in the browser.

Further learning

From here, you can discover other Subscription options, such as updating and deleting Subscriptions, as well as other predefined Messages.
Learn more about how to utilize Subscriptions in our self-paced Integration patterns with Composable Commerce module.