{
"eventId": 138833842,
"entityId": 63762876,
"listenerEntityId": 1472041829003,
"listenerEntityTechnicalName": "Transaction",
"spaceId": 30140,
"webhookListenerId": 285874,
"timestamp": "2022-08-23T14:20:53+0000"
}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 an 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.
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.
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.
You can also programmatically create a webhook URL through our API or SDK: example here.
A listener can listen on state changes of particular entities. Means when an entity changes into 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.
You can also programmatically create a listener using our API or SDK: example here.
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. |
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.
{
"eventId": 138833842,
"entityId": 63762876,
"listenerEntityId": 1472041829003,
"listenerEntityTechnicalName": "Transaction",
"spaceId": 30140,
"webhookListenerId": 285874,
"timestamp": "2022-08-23T14:20:53+0000"
}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.
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 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.
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.