![]() | API Integration with webhook notifications is a way to retrieve new data whenever an event occurs (i.e., a change has been made). |
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). | ![]() |
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. |
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 |
resources.links | API address to the updated entity (resource). | Yes |
locales.updated | The locale used while updating the entity. | Yes |
updated_items | An array of objects. Each object defines the exact item that has been updated. Possible items:
| 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"
}
}