#Concepts

#Subscriber

A subscriber represents the connection to a specific PIM instance and acts as the key reference for managing subscriptions and receiving events. It requires a connection to this PIM, so each subscriber is tied to a single PIM instance and connection. In a multi-tenant context—such as when your App is installed on multiple PIM instances—users must create a separate subscriber for each PIM instance to ensure accurate event handling across all instances.

The following properties represent a subscriber:

The statuses for a subscriber are:

For comprehensive details on managing subscribers, consult the complete API reference here.

#Subscription

A subscription is an enrollment for one or more event types from a specified source to a particular destination. By adding a new subscription, you ensure that you receive notifications whenever a tracked event occurs in your Akeneo system. Each subscription is linked to a single subscriber.

The following properties represent a subscription:

The statuses for a subscription are:

#Subscription types

#Pub/Sub subscription

#Configuration

For the pubsub subscription type, the config property needed when creating the subscription requires both the project ID and the topic ID.

    {
        "source": "pim",
        "subject": "https://my-pim.cloud.akeneo.com",
        "events": [
            "com.akeneo.pim.v1.product.updated"
        ],
        "type": "pubsub",
        "config": {
            "project_id": "your_google_project_id",
            "topic_id": "your_google_pubsub_topic_id"
        }
    }
    

#Allow the Event Platform to publish in your Pub/Sub topic

To use a Pub/Sub subscription, you need to complete a few additional steps to ensure we have permission to publish into your Pub/Sub topic:

• In the Google Cloud console, go to "Pub/Sub > Topics"
• Next to the topic you want to use, click "…" and then "View permissions"
• Click on ADD PRINCIPAL
• Past the following service account address into the "New principals" text box: delivery-sa@akecld-prd-sdk-aep-prd.iam.gserviceaccount.com
• In the Role drop-down list, select "Pub/Sub" and "Pub/Sub Publisher"
• Click "Save"

For comprehensive details on managing subscriptions, consult the complete API reference here.

#HTTPS subscription

#Configuration

For the https type, the config property requires:

• a URL using the HTTPS protocol;
• an endpoint accessible through public internet, without any form of authentication or redirection.

Additionally, it requires at least a primary secret (with an optional secondary secret) to sign the messages sent to the specified URL.

    {
      "source": "pim",
      "subject": "https://my-pim.cloud.akeneo.com",
      "events": [
        "com.akeneo.pim.v1.product.updated"
      ],
      "type": "https",
      "config": {
        "url": "https://your_webhook_url",
        "secret": {
          "primary": "your_primary_secret_to_sign_the_payload",
          "secondary": "your_secondary_secret_to_sign_the_payload"
        }
      }
    }
    

#HMAC signature for webhook payloads

HMAC (Hash-based Message Authentication Code) is a method used to verify the integrity and authenticity of a message. Using a secret key shared between the sender and receiver, HMAC ensures that the payload is untampered and originates from a trusted source.

We sign each payload for HTTPS subscriptions using the secret you provided in the configuration.

We include the signature in the payload headers:

• X-AKENEO-SIGNATURE-PRIMARY: Contains the signature using the primary secret you provided.
• X-AKENEO-SIGNATURE-SECONDARY: Contains the signature using the secondary secret you provided if you have one.
• X-AKENEO-SIGNATURE-ALGORITHM: The algorithm we used to sign the payload (currently always HmacSHA256).

We generate two signatures for each payload to facilitate secret rotation on your side.

To verify the signature on your end:

1. Receive the payload and extract the signature from the headers.
2. Using the shared secret key, compute the HMAC signature of the received payload using the same algorithm.
3. Compare the computed HMAC signature with the received HMAC signature.

This is the easiest way to ensure the message you receive comes from our platform.

#Webhooks IP Range

If you want to add an additional layer of security, you can whitelist our service’s IP range.

We currently use a static IP address provided by Google Cloud: 34.140.80.128

However, we cannot guarantee that this IP address will remain unchanged indefinitely. Therefore, we strongly recommend whitelisting the europe-west1 IP ranges from Google Cloud's IP ranges list to ensure continuous access.

#Events Format

Our platform standardises event data across services using the CloudEvents specification. CloudEvents provides a consistent structure for event data, ensuring interoperability and simplifying event handling. Each event includes essential metadata such as the event type, source, ID, and timestamp.

The cloud event will be sent in a structured mode, meaning the event data and its metadata are in the payload you'll receive. This apply to every subscription destination type.

Example of an event payload for a productDeleted event

    {
      "specversion": "1.0",
      "id": "018e197c-dfe2-70f8-9346-1a8e016f5fbb",
      "source": "pim",
      "type": "com.akeneo.pim.v1.product.deleted",
      "subject": "0190fe8a-6213-76ce-8a9f-ba36a5ef555a",
      "datacontenttype": "application/json",
      "dataschema": "https://event.prd.sdk.akeneo.cloud/spec/com.akeneo.pim.v1.product.deleted.schema.json",
      "time": "2024-03-07T15:16:37Z",
      "data": {
        "product": {
          "uuid": "3444ec1b-058e-4208-9b6c-284f47a7aa17"
        }
      }
    }
    

For more information, consult the CloudEvents spec attributes.