Extending Data with Hooks

Hooks are one of the most powerful features which offers a huge flexibility to extend accommodation, result and query core data structures on-the-fly using external web services.

Hooks must follow the OpenBooking Hook Protocol, which is described below. They can be added to your OpenBooking account in the Admin Panel.

Limits

To ensure fast processing of internal data structures, OpenBooking currently imposes the following limits on Web Hooks:

A Hook must respond within 1,000 milliseconds. After that, the connection to the Hook is closed prematurely
The data returned by the Hook must not be greater than 1,024 bytes, otherwise it will be ignored
The data returned must be JSON data

Supported data objects

The following resources can be used in Hooks:

Accommodations
Queries
Results

Currently Hooks are only triggered on the "save" event (when the object is created or updated).

Hook Protocol

1. REQUEST (OPENBOOKING -> HOOK WEBSERVICE)

A Hook Request is made by OpenBooking to the registered Hook URL every time when a Hook event occurs. A Hook must accept POST requests to the endpoint configured in the Admin Panel.

The request body will be a JSON object with the following parameters:

{
  "event": "save",
  "id": "54425a678fe20999",
  "resource": "/accommodations/54425a678fe20999",
  "data": {
    // the resource object
  }
}

2. RESPONSE (HOOK WEBSERVICE -> OPENBOOKING)

The Hook has to respond with a HTTP Status Code and a JSON body as payload as follows:

HTTP Status Code	Meaning	Usage
200	OK	Normal case when Hook could process the request and returns some data in the body.
204	No Content	If the Hook is only catching the request without actually returning data (read-only hooks). HTTP Body can be empty.
400-499	Client-side error	Something was wrong with the Hook request itself and there must be some action taken by OpenBooking. Please provide "error" field in the response body.
500-599	Server-side error	Something was wrong server-side (Hook-side) that must be fixed by the Hook owner.

Response payload example:

{ 
  "data" : ...,
    // arbitraty hook data here, can be any value
    // should be a JSON object, i.e. 
    // { "stv_id": "123456",
    //   "st_key": "ST-12345" }
  "error": "string"
    // Attach any debug information in the error field as a string in case
    // your Hook encountered an error. The "error" field will only be 
    // read by OpenBooking if the HTTP Status Code is greater than or equal 400
}

Any Hook responses with HTTP Status Code 200-499 will be saved in the "hookData" data field on the source object. HTTP Status Codes from 500 upwards are logged internally. To prevent overwriting of Hook data because of a temporary server failure, the hookData will not be modified.

Storage of Hook data

"hookData" will contain a key with the Hook "parameter" name, which was configured in the Admin Panel:

Example of stored Hook data:

{ 
    "type" : "hotel", 
    "place" : "OCH660", 
    "name" : {
        "de" : "Hôtel de Charme la Poste, Anzère"
    }, 
    "hookData" : {
        "contentScore" : {
            "statusCode" : 200, 
            "data" : {
                "points" : 80, 
                "maxPoints" : 150
            }, 
            "executed" : "2015-11-30T20:58:14.710Z"
        }, 
        "minPrice" : {
            "statusCode" : 200, 
            "data" : {
                "min_price_seen" : 120
            }, 
            "executed" : "2015-11-30T20:58:14.643Z"
        }
    }
}

The Hook object contains the following fields:

Field	Description
statusCode	The original HTTP status code, the Hook was responding with.Or, 408 (Request Timeout) if the Hook did not respond within the time limit.
executed	The timestamp when the Hook was executed.
data	The actual data the Hook returned.

OpenBooking currently offers the following standard Hooks that can be used by all clients:

Name	Object Type	Description
Content Score	Accommodation	Calculated a scored based on the quality of the content, like descriptions, images etc.
Min Price	Accommodation	Adds the minimum price the system finds in the result cache for this accommodation.
Hotelleriesuisse	Accommodation	Extracts official classification information from Hotelleriesuisse core database "Swiss Hotel Data".

If you want to use one of the Standard Hooks, call your OpenBooking account manager.