#Concepts

#Subscriber

Simply put, a subscriber represents a connection to a specific event source, like a PIM. While you can attach multiple subscribers to your source, the general recommendation is to configure only one. However, your setup will require creating various subscribers for a multi-tenant context.

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

#HTTP subscription

#Configuration

For the https type, the config property requires:

• a URL using the HTTPS protocol;
• a URL that accepts HEAD requests and responds with an HTTP status code other than 404 or 5xx.

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

{
      "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 is from us.

#Pub/Sub subscription

#Configuration

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

{
        "project_id": "your_google_project_id",
        "topic_id": "your_google_pubsub_topic_id"
    }
    

#Allow the Akeneo 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.

#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.

Example of an event payload for a productDeleted event

    {
      "specversion": "1.0",
      "id": "018e197c-dfe2-70f8-9346-1a8e016f5fbb",
      "source": "akeneo-event-platform",
      "type": "com.akeneo.pim.v1.product.deleted",
      "subject": "0190fe8a-6213-76ce-8a9f-ba36a5ef555a",
      "datacontenttype": "application/json",
      "dataschema": "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.

#Retry policies

Ensure reliable message processing in distributed systems. Retry policies help manage transient failures and guarantee message delivery even when issues occur.

Here, we outline the key retry policies implemented in our system.

#ACK timeout

ACK timeout ensures that messages are acknowledged within a specified period. In our system, the ACK timeout is set to 3 seconds. If an acknowledgment isn't received within this timeframe, the message is retried. This mechanism prevents message loss due to slow consumers or temporary network delays.

In case of HTTPs subscription, your endpoint must handle the event as fast as it can. Our recommendation is to put the message in a queuing system or in a database, and process the event asynchronously.

#At least once

The at least once delivery guarantee means in case of delivery failure, our retry policy will try to deliver the event again. This policy ensures that no message is lost until reasonable limits, though it may result in duplicate deliveries.

Additionally, due to this system, the order of events may be unpredictable. Developers should design their systems to handle potential duplicates gracefully, ensuring idempotent processing.

To help identify duplicated events, use both fields id and time from the event, which provide unique identifiers and publication timestamp for each event.

#Retry back-off

Back-off policies manage the intervals between retry attempts. We handle retry back-off internally, and it is not configurable per tenant.

Instead of immediate retries, the system waits for a specified back-off period, which can vary depending on the service load. If the retry limit is reached without a successful acknowledgement, the event is lost.

Properly handling transient issues through back-off and retry helps maintain system stability and reliability under varying loads.

#Suspend/Revocation policies

Our system enforces strict revocation policies to maintain the integrity and reliability of event delivery.

If your endpoint responds with a HTTP 404 Not Found status, we will revoke your subscription, necessitating the creation of a new subscription.

If your endpoint repeatedly fails with HTTP 429 Too Many Requests or 5XX Server Error statuses, we will suspend your subscription. You will then need to manually resume it using the API.

For both revocations and suspensions, we will notify the technical email address you provided, informing you of any actions taken.