Notifications

API Integration with webhook notifications is a way to retrieve new data whenever an event occurs (i.e., a change has been made).

Not only are webhooks significantly more efficient than API Pull Requests, they're an essential complement to API-based application integration because they free up time and resources on both sides.

API Polling vs Webhook Notifications

The main difference is that APIs send requests to get responses, whereas webhooks automatically send them.

While an API Pull Request would send a request for new events at a predetermined frequency and wait for the endpoint to respond (aka polling), webhooks automatically notify you in real-time when certain events occur (e.g., data has been modified -creation, update, deletion).

The goal of Quable Webhook Notification Service is to alert your application whenever a change has been made to your Quable PIM data.

Notification Endpoints

Webhook notifications are sent to dedicated URLs called endpoints. These endpoints are used when you subscribe to listen for certain events. Once you've set up a subscription, notifications are sent in real-time to the designated endpoint when the event occurs.

Handling Notifications

Once you've set up subscriptions and are receiving notifications on events, the HTTP status code returned to Quable PIM API determines what happens next.

The Quable Webhook Notification Service sends its call to the designated endpoint and waits for a 2xx HTPP response code.

Any other response code will be considered as a failure and the notification will be retried. A maximum of two retries will be sent at five minutes intervals. After the third consecutive failure, the webhook is automatically disabled and must be manually re-enabled.

🚧
The SSL certificate for the endpoint's domain must be valid.

Notification Payload

HTTP requests sent by Quable Webhook Notification Service is composed of a JSON Payload. The structure of the notification payload is the same no matter the event you've subscribed to.

The following is a description of every item that can be included in a notification:

JSON Key	Description	Mandatory
`uuid`	The unique identifier of the event.	Yes
`code`	The event code (an event you've subscribed for).	Yes
`links`	The API address of the event.	Yes
`created_at`	The date and time of the event.	Yes
`created_by`	The user who triggered the event.	Yes
`resource`	Information about the updated entity.	Yes
`resource.code`	The unique identifier of the entity involved in the event.	Yes
`resource.type`	The unique identifier of the entity type (i.e.,asset, classification, document, link, predefined value, variant).	Yes
`resource. document_type_code`	The unique identifier of the document type.	Yes (if `resource.type` = "document")
`resources.links`	API address to the updated entity (resource).	Yes
`locales.updated`	The locale used while updating the entity.	Yes
`locales.inherited`	An array of locales impacted by an update. This array should be monitored because it uses inheritance.	Yes
`updated_items`	An array of objects. Each object defines the exact item that has been updated. Possible items: asset (media) attribute (field) document link predefined value variant (sku)	No
`process.correlationId`	A unique ID for Quable Services	Yes
`process.id`	The unique ID of the process (import or bulk-edit)	No
`process.type`	If the event has been generated by a process, then this attribute will tell so :"import" "bulk_edit"	No

Example

The following is an example of a document.update event:

{
  "uuid": "ce6c64a3-4f27-4b0e-862c-ee780eae06d1",
  "code": "document.update",
  "links": [
    {
      "rel": "self",
      "href": "/events/ce6c64a3-4f27-4b0e-862c-ee780eae06d1"
    }
  ],
  "created_at": "2020-06-18T11:48:17+00:00",
  "created_by": "john_doe",
  "resource": {
    "code": "product_blue_pant",
    "type": "document",
    "document_type_code": "product",
    "links": [
      {
        "rel": "self",
        "href": "https://{{YOUR-PIM}}.quable.com/api_1.php/documents/product_blue_pant"
      }
    ],
    "locales": {
      "updated": [
        "fr_FR"
      ],
      "inherited": [
        "en_GB",
        "fr_FR"
      ]
    },
    "updated_items": [
      {
        "type": "field",
        "code": "color"
      },
      {
        "type": "field",
        "code": "name"
      }
    ]
  },
  "process": {
    "type": "bulk_edit",
    "id": "20aaabe5-5dcb-4cbb-80e8-ba75c30bbce0",
    "correlationId": "A4548C0354f48954x-565654qsds9chg564jhg78"
  }
}