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.

  • 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.

Once you receive the notification on your URL you should call our API to read the state of the entity that changed. This has the main benefit that we are able to notify you also on unsecured URLs and we do not have to exchange sensitive data directly with your system.

In order to read the state of the entity and further details you should use the corresponding read endpoint in the API Documentation using the entityId.

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