Receiving events

This page covers the mechanics of the events Mirakl Connect sends you:

• how the events reach your connector,
• what every event looks like on the wire,
• how to configure the destination they are delivered to.

It applies to every event, whatever domain it belongs to.

For what each event means, and which business domain it serves, refer to the API and event directory. For the complete payload of each one, refer to the Event APIs reference.

Every event, on every destination, arrives in the same envelope: a small set of metadata fields that wraps a body specific to the event.

{
  "id": "01jt31mw7wy3x4zs55kawgg1xe",
  "type": "ORDER_ACTION",
  "time": "2026-07-07T10:32:00Z",
  "data": {
    "...": "event-specific fields for this type"
  }
}

• id: a unique identifier for this event, in the ULID format. Use it to deduplicate: if you see the same id twice, you have already handled it.
• type: the type of the event, which tells you how to interpret data. On an OrderActionEvent, it also names the specific action Mirakl Connect requests, and it selects the shape of data.
• time: when Mirakl Connect produced the event.
• data: the payload specific to the event. Its shape depends on type, and the Event APIs reference documents it.

Because the envelope is constant, a single layer in your connector can deserialize every event and route it by type, independently of the destination.

You do not register a subscription through a self-service API. Mirakl provisions your subscriptions for you. You provide the event types you want and the configuration of the destination you chose, and the Mirakl Connect Partner Team registers the subscriptions. Any secret in that configuration is stored encrypted at rest, and the delivery is always over TLS.

The event delivery is configured separately for each environment, so your test destination and your production destination are independent. Refer to Environments.

Mirakl Connect delivers every event to a queue or a topic that you own. It supports three types of destination, and all three receive the identical payload. They differ in what you must provision, and in how the ordering is preserved.

A queue holds an event until your connector processes it, so a restart, a deployment, or an outage of your connector loses nothing. Your connector controls the rate at which it consumes, and it acknowledges each message itself.

The sections below describe the authorization and the configuration each destination requires. Each one grants Mirakl Connect the permission to publish, and no destination requires your connector to expose an endpoint to Mirakl Connect. Ordering per destination collects how the ordering works on each one.

Mirakl Connect is compatible with two types of queue:

• The standard queue type.
• The FIFO queue type, for First In, First Out.

In both cases, configure the queue with a MaximumMessageSize of 256KB.

The authorization is based on IAM. You must grant the sqs:SendMessage permission on your queue to the Mirakl Connect IAM user, before you register the queue in Mirakl Connect.

Mirakl Connect manages a different user for each stage of your application, to prevent the publication of test data to a production environment.

To configure an AWS SQS queue, you must provide:

• the AWS region where your SQS queue is located,
• the queue URL of your SQS queue,
• the type of the queue, and if it is FIFO, check the FIFO queue checkbox.

The authorization is based on IAM. You must grant the pubsub.topics.publish permission on your topic to the Mirakl Connect service account user, before you register the topic in Mirakl Connect.

Mirakl Connect manages a different user for each stage of your application, to prevent the publication of test data to a production environment.

To configure a GCP Pub/Sub topic, you must:

• provide the project ID where your topic is created,
• provide the topic name of your Pub/Sub topic,
• optionally, configure the ordering, if you have a subscription with ordering, to receive the messages in the order the Pub/Sub service receives them. For that, you must:
  • check the Enable message ordering option,
  • provide a regional gRPC service address, which is the regional endpoint to use to send your Pub/Sub messages, in the form region-pubsub.googleapis.com. Refer to Pub/Sub APIs Overview, Google Cloud.

To authenticate on your Service Bus and authorize the sending of messages, 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 receives your events, which is a queue or a topic.
• Go to Shared access policies.
• Create a new policy.
• Add the Send permission to the policy.
• Copy the primary connection string, to configure your Service Bus.

Once you have done that, 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 of 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, either Queue or Topic,
• optionally, additional settings:
  • Enable partitioning: request this option if partitioning is activated on your Azure Service Bus. Mirakl then associates a partition key with each message, which is the object ID for the type of the event.
  • Enable sessions: request this option if sessions are activated on your Azure Service Bus. Mirakl then associates a session ID with each message, to guarantee that the messages are processed First In, First Out.

Mirakl Connect guarantees the ordering for each partition key. Events that share a business key are delivered in order relative to one another, and there is no guarantee across different keys. The key is the object ID for the type of the event: the SKU of the offer, its product_id, for the offer and the price and stock events, and the order for the order action events.

Whether that ordering survives to your consumer depends on the destination, and on you enabling the ordering feature of that destination. Mirakl Connect sets the appropriate key on every message, and the destination honours it only if you configure it to.

The ordering is only meaningful alongside the deduplication, because Mirakl Connect can also deliver the same event again. Refer to Ordering for how to preserve the order for each key while you parallelize across keys.

The delivery is at-least-once, and ordered only for each partition key. Mirakl Connect retries the deliveries that fail, on a windowed-backoff schedule. There is no dead-letter queue: once the retries are exhausted, Mirakl Connect abandons the event. Your connector must therefore recover the state it missed through reconciliation, not through a repeat delivery.

Best practices gives the rules you build around these guarantees: how to deduplicate on the event id, how to keep the handlers idempotent, and how to preserve the order for each key.

Your connector acknowledges each message on its own queue, and the queue decides what an unacknowledged message becomes. The acknowledgement is the mechanism of the destination you chose, and Mirakl Connect takes no part in it:

• on AWS SQS, your consumer deletes the message,
• on Google Cloud Pub/Sub, your subscriber sends the ack,
• on Azure Service Bus, your receiver completes the message.

A message your connector does not acknowledge returns to the queue once its visibility timeout, its ack deadline, or its lock expires, and your connector receives it again.

Acknowledge a message once you have stored the event durably, and not once you have finished the work it asks for. That keeps the message off the queue while the slow work runs, and the deduplication on the event id covers the message that comes back anyway.

An acknowledgement confirms receipt alone. It states nothing about the outcome of the work, which you report through the REST APIs.

• Calling the APIs: the counterpart to this page, for the calls you make.
• Best practices: the rules on idempotency, ordering, retries, and errors that your handlers build around.
• Authorization: the token your connector uses for its own API calls.
• Environments: the addresses for each environment, and where the event delivery is configured separately.
• API and event directory: what each event means, grouped by business domain.
• Event APIs reference: the complete payload of every event.