Documentation

1Introduction

A webhook can be used to notify another application about events. Webhooks are generally triggered by some event for example to notify your application about a status change of a entity.

There are two concepts to notify an application changes. One is polling and the other one is pushing. Polling is not optimal because normally there is no update and the poll is wasted. As such we employ pushing updates. Webhooks is a concept by which the application which is interested in updates gets notified by a HTTP request. Which means the application can register itself for certain events and we send a HTTP request when such an event occurs.

2Webhook Configuration

All configuration details can be set inside the space Space > Connect > Webhooks. You can define here the URL as well as chose from the different events for which you want to receive a HTTP call.

2.1URLs

All URLs you want a webhook delivered to are configured centrally inside Space > Connect > Webhooks > URL. Click to add a webhook URL. Managing the URLs centrally helps you to more easily manage changes to URLs so that you not have to touch every webhook listener configuration.

2.2Webhook Listeners

A listener can listen on state changes of particular entities. Means when an entity changes into a the specified state the URL will be invoked. Only certain entities are enabled to be subscribable by a webhook listener. A Webhook Listener can be created under Space > Connect > Webhooks > Listener.

2.3Invocations

A log of all triggered webhooks can be seen under Space > Connect > Webhooks > Invocations. By clicking on the invocation you can see the error in case the webhook failed including the response that we received from your server.

Note
We try to deliver the event until we reach a certain number of attempts. The time between the attempts is increased after each attempt. When the delivery keeps failing the listener will be deactivated to prevent further invocation of a potentially dead listener.

3Integration Details

The HTTP request which is sent for a state change of an entity contains the following data:

  • eventId: A unique id which identifies the state change. This will be always different for each notification.

  • entityId: The ID of the entity which was changed.

  • listenerEntityId: The listener entity indicates which entity type was changed.

  • listenerEntityTechnicalName: The listener entity technical name provides a name for the entity type.

  • state: The state to which the entity has changed to.

  • spaceId: The space id to which the entity which has been changed belongs to.

  • webhookListenerId: The ID of the listener.

  • timestamp: The time when the state change has occurred.

To check the authenticity of the HTTP request sent by our application we add a dedicated HTTP header X-Request-Signatures. This header contains a signature calculated in a similar way as the API call is signed.

The X-Request-Signatures may contains two values (separate by a comma) when there are multiple HMAC keys configured for the webhook identity. As such an implementation has to verify if one of the provided signatures is correct.

The validation of the signature is calculated by applying the same HMAC as for signing an API request. Except that the whole body of the HTTP message has to be used as the input. Below there is some pseudo code to demonstrate the calculation. The hmac is a function which is able to calculate the HMAC. The httpBody is the whole body sent and the secret is the key you have setup for the webhook identity. The body should be taken as it is and it should not be modified. Eventually the message may contain more properties in the future. As such the implementation should not rely on a specific order or a specific number of properties.

signature = hmac(httpBody, secret);

Below you find a HTTP message as sent by the webhook notification service:

POST /some/url HTTP/1.0
Content-Type: application/json
charset: utf-8
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.125 Safari/537.36
X-Request-Signatures: JIn0_PobeXY3u14tUu3NCnNjQ0qxNmq3qiKGBfN0ldIMNVna3iS04ZWV0XujeQFkyBmHHo19qIMnd0oEsW5Anw,2qXGF_qbfa_zLA1VI8IMezmjOuFpvjXh2a20hLIid9Xd2qZvAdkyuIcZhUnmxM62U4pO5xq_TN4hVaOeCpevqA
Cache-Control: no-cache
Pragma: no-cache
Host: some-host-which
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Content-Length: 174

{"eventId":4,"entityId":3,"listenerEntityId":123123123,"listenerEntityTechnicalName":"SomeEntityName","state":"SOME_STATE_NAME","spaceId":1,"webhookListenerId":3,"timestamp":"2016-08-24T07:53:37+0000"}

4Firewall Configuration

In order for the webhooks to function properly it is important that your firewall and server configuration allows communication from our servers. This document provides all the information required to configure the your firewalls to allow traffic between your infrastructure and our services, thereby minimising the risk of communication errors/issues.

This document assumes that the merchant is familiar with the procedures for configuring firewalls, routers or any other devices used to block traffic on the merchant’s network.

4.1Public IP Addresses

The following lists contains IP addresses that must be white listed to allow the communication between your infrastructure and our platform. We send the HTTP request from these IP addresses.

  • 52.212.252.118
  • 52.212.252.150