# 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](/content/product/connect-channel-platform/getting-started/api-and-event-directory). For the complete payload of each one, refer to the [Event APIs reference](/content/product/connect-channel-platform/webhooks/webhook). ## The event envelope Every event, on every destination, arrives in the same envelope: a small set of metadata fields that wraps a body specific to the event. ```json { "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](/content/product/connect-channel-platform/webhooks/webhook/webhooks/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](/content/product/connect-channel-platform/webhooks/webhook) 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. ## How your subscription is provisioned 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](/content/product/connect-channel-platform/getting-started/environments). ## Choosing a destination **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. | Destination | How events reach you | Ordering option | What you provide | | --- | --- | --- | --- | | [AWS SQS](#amazon-web-services-sqs) | Mirakl Connect sends to your queue, and your connector polls it. | FIFO queue | The region and the queue URL | | [Google Cloud Pub/Sub](#google-cloud-pubsub) | Mirakl Connect publishes to your topic, and you pull or push from a subscription. | Message ordering | The project ID and the topic name | | [Azure Service Bus](#microsoft-azure-service-bus) | Mirakl Connect sends to your queue or your topic. | Sessions | The connection string and the entity type | 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](#ordering-per-destination) collects how the ordering works on each one. Your connector never authenticates Mirakl Connect, and Mirakl Connect presents it no credential. You authorize Mirakl Connect to publish to your queue or your topic instead. The access token your connector holds authenticates the REST calls it makes, and it plays no part in the event delivery. Refer to [Authorization](/content/product/connect-channel-platform/developer-guide/authorization). ## Amazon Web Services SQS 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`. ### Authorization 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. | Stage | Mirakl Connect IAM user account | | --- | --- | | TEST | `arn:aws:iam::689046024352:user/public/app-webhook-connect-test` | | PROD | The Mirakl Partner team provides it | The queue can also be encrypted. If it is, you can configure two modes of encryption: * SSE-SQS, which is server-side encryption with keys that SQS manages. In this case, no additional configuration is needed. * SSE-KMS, which is server-side encryption with the AWS Key Management Service. In this case, you must authorize an external account to use the KMS key that SQS uses. The Mirakl Partner team provides that account. ### Configuration 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. ## Google Cloud Pub/Sub ### Authorization 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. | Stage | Mirakl service account | | --- | --- | | TEST | `app-webhook-connect-test@app-webhook-connect-beta-ca5d.iam.gserviceaccount.com` | | PROD | The Mirakl Partner team provides it | ### Configuration 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](https://cloud.google.com/pubsub/docs/reference/service_apis_overview#list_of_locational_endpoints). ## Microsoft Azure Service Bus ### Authorization 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. ### Configuration 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. ## Ordering per destination 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. | Destination | Mechanism | What you must do | | --- | --- | --- | | AWS SQS | Mirakl Connect sets the `MessageGroupId` to the object ID. | Use a **FIFO** queue, and check the **FIFO queue** option. A standard queue does not preserve the order. | | Google Cloud Pub/Sub | Mirakl Connect sets an ordering key on the message. | Check **Enable message ordering**, provide the **regional gRPC service address**, and use a subscription with the ordering enabled. | | Azure Service Bus | Mirakl Connect sets a session ID, with sessions, or a partition key, with partitioning, to the object ID. | Request **Enable sessions** for a FIFO guarantee, and **Enable partitioning** if partitioning is active on your entity. | The ordering is only meaningful alongside the deduplication, because Mirakl Connect can also deliver the same event again. Refer to [Ordering](/content/product/connect-channel-platform/developer-guide/best-practices#ordering) for how to preserve the order for each key while you parallelize across keys. ## Delivery semantics 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](/content/product/connect-channel-platform/developer-guide/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. ## Acknowledging a message **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. ## Related pages * [Calling the APIs](/content/product/connect-channel-platform/developer-guide/calling-the-apis): the counterpart to this page, for the calls you make. * [Best practices](/content/product/connect-channel-platform/developer-guide/best-practices): the rules on idempotency, ordering, retries, and errors that your handlers build around. * [Authorization](/content/product/connect-channel-platform/developer-guide/authorization): the token your connector uses for its own API calls. * [Environments](/content/product/connect-channel-platform/getting-started/environments): the addresses for each environment, and where the event delivery is configured separately. * [API and event directory](/content/product/connect-channel-platform/getting-started/api-and-event-directory): what each event means, grouped by business domain. * [Event APIs reference](/content/product/connect-channel-platform/webhooks/webhook): the complete payload of every event.