Notifications

673673API 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.
23692369

Notification Endpoints

9898Webhook 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

9898Once 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)

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"
      }
    ]
  }
}