This section provides information on events in Mirakl and how to implement them.
Events allow applications to send automated messages and information to other applications. They provide instant, real-time notifications, eliminating the need for polling for results or statuses. Mirakl Connect uses this technology to enhance the integration provided by APIs.
Mirakl Connect supports three destination types:
- Amazon Web Services - Simple Queue Service (AWS SQS)
- Google Cloud Platform Pub/Sub (GCP Pub/Sub)
- Microsoft Azure Service Bus
The complete documentation of event payloads is available here.
How do Events work?
- The user provides the destination for the events.
- Each time a change occurs, Mirakl Connect automatically sends the event to the client application.
- The client application acknowledges the event and processes the received data.
The AWS SQS integration allows you to store and receive messages without the risk of data loss. Mirakl Connect is compatible with two queue types:
- Standard queue type
- FIFO (First In, First Out) queue type: This method processes the first entered data, or 'head' of the queue, first. It's similar to a queue system where the earliest arrival gets served first, essential for tasks like scheduling and packet management in computers.
In both cases, configure the queue with a MaximumMessageSize of 256KB.
Authentication is based on IAM. You must grant the sqs:SendMessage permission to your queue for the Mirakl Connect IAM user before registering it on the Mirakl Connect platform.
Mirakl Connect manages different users depending on your application's stage to prevent testing data from being published to a production environment.
| Stage | Mirakl Connect IAM User Account |
|---|---|
| TEST | arn:aws:iam::689046024352:user/public/app-webhook-connect-test |
| PROD | Is provided by the Mirakl Partner team |
Note: The queue can also be encrypted. If so, two encryption modes can be configured:
- SSE-SQS (Server Side Encryption using SQS-managed encryption keys). In this case, no additional configuration is needed.
- SSE-KMS (Server Side Encryption using AWS Key Management Service). In this case, an external account must be authorized to use the KMS key used by SQS. This account is provided by the Mirakl Partner team.
To configure an AWS SQS you must provide:
- The AWS Region where your SQS queue is located
- The Queue URL of your SQS queue
- The type of queue, if FIFO, check the FIFO queue checkbox.
For FIFO queues, Mirakl Connect provides a MessageGroupId corresponding to the Object ID, depending on the event type, to ensure correct ordering of events for an entity.
You must provide this data to the Mirakl Connect Partner Team to be registered on the Mirakl Connect Platform.
Google Cloud Platform Pub/Sub (GCP Pub/Sub) is a messaging solution provided by Google Cloud Platform. It allows you to publish to a topic and consume from subscriptions linked to it using either a pull or push method.
Authentication is based on IAM. You must grant the pubsub.topics.publish permission on your topic to the Mirakl Connect service account user before registering it on the Mirakl Connect platform.
Mirakl Connect manages different users depending on your application's stage to prevent testing data from being published to a production environment.
| Stage | Mirakl Service Account |
|---|---|
| TEST | app-webhook-connect-test@app-webhook-connect-beta-ca5d.iam.gserviceaccount.com |
| PROD | Is provided by the Mirakl Partner team |
To configure a GCP PubSub you must:
Provide the Project ID where your topic is created
Provide the Topic name of your Pub/Sub topic
Optionally, configure ordering if you have a subscription with ordering to receive messages in the order the Pub/Sub service receives them. You must:
- Check the Enable message ordering option
- Provide a Regional gRPC service address: the regional endpoint to use for sending your Pub/Sub messages in the
region-pubsub.googleapis.comform. (Refer to Pub/Sub APIs Overview - Google Cloud).
When ordering is configured, Mirakl Connect provides an ordering key on the Pub/Sub message corresponding to the Object ID, depending on the event type.
You must provide this data to the Mirakl Connect Partner Team to be registered on the Mirakl Connect Platform.
Azure Service Bus is a fully managed message broker that supports queues and topics.
- Message queues are used for point-to-point communication, where messages are ordered on arrival.
- Topics provide a publish/subscribe solution. Messages sent to a topic are published in all subscriptions associated with the topic. A subscription then behaves as a queue.
To authenticate on your Service Bus and authorize message sending, create a shared access policy with sending rights on the entity.
To create a Shared Access Policy with sending rights, follow these steps:
- Go to your Service Bus namespace in the Azure Portal.
- Select the entity that will receive your events (a queue or a topic).
- Go to Shared access policies.
- Create a new policy.
- Add the
Sendpermission to the policy. - Copy the Primary Connection String to configure your Service Bus.
Once done, you can configure your Azure Service Bus connector.
To configure an Azure Service Bus connector, you must provide:
- The connection string associated with the shared access policy for the Service Bus. For example:
Endpoint=sb://YOUR_SERVICEBUS.servicebus.windows.net/;SharedAccessKeyName=SHARED_ACCESS_POLICY_NAME;SharedAccessKey=SHARED_ACCESS_KEY;EntityPath=QUEUE_NAME - The Entity type of your Azure Service Bus (Queue or Topic).
- Optionally, provide additional settings:
- Enable partitioning: If activated on your Azure Service Bus, request this option. Mirakl will associate a partition key to each message corresponding to the object ID, depending on the webhook type.
- Enable sessions: If activated on your Azure Service Bus, request this option. Mirakl will associate a session ID to each message to ensure a FIFO (First In, First Out) guarantee on message processing.
You must provide this data to the Mirakl Connect Partner Team to be registered on the Mirakl Connect Platform.