The Events API basics

#Subscribe and Receive events

#Subscribing to events

To subscribe events, you need to start by configuring an Akeneo PIM. You will find all the steps to follow in the Help center page Subscribe to events:

how to activate the event subscription,
how and where to setup and verify your server URL,
how to manage the Akeneo PIM permissions to filter events.

#Events API Request URLs

Request URL receives an HTTP POST containing data in response to activity.

In the Events API, your Events API Request URL is the target location. Akeneo PIM will deliver all the events, regardless of the event type, to this location.

Since your connected application will have only one Request URL, maybe you'll need to do an additional dispatch or routing server-side after receiving event data.

Your Request URL will receive JSON-based payloads containing wrapped event types.

#Receiving Events

Your Event API Request URL will receive events matching your subscriptions. The message which delivers these events can contain up to 10 events.

Be careful as some events can be sent in the wrong order, more than once, or get lost altogether.

This is why the event_id and event_datetime are essential.

The event_id uniquely identify each event. This allows you to log the events you have already processed and not handle more than once.
The event_datetime allows you to ignore an outdated event.

#Events dispatched as JSON

When an event occurs, Akeneo PIM send an HTTP POST request to your Request URL. This request is JSON-based (Content-Type: application/json) and contains wrapped events.

{
        "events": [
            {
                "action": "product.created",
                "author": "julia",
                "author_type": "ui",
                "event_id": "6ad821d8-2468-4632-89d2-92e442c72313",
                "event_datetime": "2020-01-01T00:00:00+00:00",
                "pim_source": "staging.akeneo.com",
                "data": {
                    "resource": {...}
                }
            }
        ]
    }

#Request header

Name	Description
`X-Akeneo-Request-Signature`	The signature of the payload to verify the authenticity of the request
`X-Akeneo-Request-Timestamp`	The time at which the request was sent (unix timestamp in seconds)

#Request body

Name	Description	Example	Format
`action`	Helps you identify the API event type you received, which action has been done in the PIM.	`product.created`
`event_id`	Unique identifier of the event. It allows you to ensure you received the same API event only one time.	`6ad821d8-2468-4632-89d2-92e442c72313`	UUID V4
`event_datetime`	Contains the date and time of the event.	`2020-01-01T00:00:00+00:00`	Format ISO 8601
`author`	Tells you who performed the action.	`Julia` or `magento_0000`
`author_type`	Type of user who performed the action. Like Julia, it can be a UI user or a REST API call coming from another application.	`ui` or `api`
`pim_source`	Identify which Akeneo PIM sent the event.	`demo.akeneo.com`	From `AKENEO_PIM_URL` environment variable
`data`	Contains the resource data. Learn more about the data wrapper, including its JSON schema, on our Events API Reference.