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.