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.


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


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


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

HTTP Status Code





Normal case when Hook could process the request and returns some data in the body.


No Content

If the Hook is only catching the request without actually returning data (read-only hooks). HTTP Body can be empty.


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.


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:




The original HTTP status code, the Hook was responding with.Or, 408 (Request Timeout) if the Hook did not respond within the time limit.


The timestamp when the Hook was executed.


The actual data the Hook returned.

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


Object Type


Content Score


Calculated a scored based on the quality of the content, like descriptions, images etc.

Min Price


Adds the minimum price the system finds in the result cache for this 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.