Notifications

673API 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.
2369

Notification Endpoints

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

98Once 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 KeyDescriptionMandatory
uuidThe unique identifier of the event.Yes
codeThe event code (an event you've subscribed for).Yes
linksThe API address of the event.Yes
created_atThe date and time of the event.Yes
created_byThe user who triggered the event.Yes
resourceInformation about the updated entity.Yes
resource.codeThe unique identifier of the entity involved in the event.Yes
resource.typeThe unique identifier of the entity type (i.e.,asset, classification, document, link, predefined value, variant).Yes
resource. document_type_codeThe unique identifier of the document type.Yes
(if resource.type = "document")
resources.linksAPI address to the updated entity (resource).Yes
locales.updatedThe locale used while updating the entity.Yes
updated_itemsAn 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.correlationIdA unique ID for Quable ServicesYes
process.idThe unique ID of the process (import or bulk-edit)No
process.typeIf 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"
  }
}