# Notifications

By

The Quable Team

●

Published 2023-11-21

API polling VS webhook notifications
Notification endpoints
Handling notifications
The importance of asynchronous processing
Notification payload
Example

The main difference is that APIs send requests to get responses, whereas webhooks automatically send the responses without the need for any request.

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 - either its a creation, an update or a deletion).

API Polling

Imagine a character (representing a customer or an application) looking at his watch and regularly coming to a door (representing an API) to ask if there is any new data.
It's a repetitive process where the character keeps coming back, even though nothing has changed.

Webhook Notifications

Now imagine a doorbell or bell. Instead of the character regularly coming to the door, the door (the API) rings the bell or activates the doorbell to notify the character as soon as there is new data.
This is more efficient because the character doesn't need to check constantly. He simply waits to be notified.

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

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

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 200s HTTP response code (indicating success).

Bad response from your service
Any other response code will be considered as a failure and the notification will be retried.

Response time too slow
Any response longer than 5 seconds will be considered a failure and the notification will be retried.

Automatic shutdown
A maximum of two retries will be sent at five minutes intervals.
After the third consecutive failure (bad response / too slow), the webhook is automatically disabled and must be manually re-enabled.

Asynchronous processing is important for:

Stability and Reliability
Direct processing of webhook notifications can jeopardize system stability. When faced with numerous or complex requests, servers may be overloaded, leading to slow responses or even outages. By queuing notifications for later processing, the load is evenly distributed, enhancing system stability and reliability.

Traffic Peak Management
Webhooks can create significant traffic spikes, particularly during unforeseen events. Delayed processing allows your system to handle these surges without being overwhelmed, maintaining optimal performance under pressure.

Enhanced Security
Immediate processing of notifications can make your system more susceptible to attacks like Denial of Service (DoS). Deferred processing provides more time to verify request authenticity and implement appropriate security measures.

Flexibility and Scalability
Storing notifications for later processing offers the flexibility to manage data on your own terms and schedule. This approach adapts processing based on available resources, ensuring better scalability of your infrastructure.

Resource Optimization
Deferred processing enables more efficient resource utilization. Instead of using resources for each individual notification, grouping and processing them together reduces costs and enhances overall efficiency.

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:

{
  "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://{{instance}}.quable.com/api/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"
  }
}