Documentation
Documentation
    • English (United States)
Webhooks

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

2Webhook Configuration

All configuration details can be set inside the space Space > Settings > General > Webhook Listeners. 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 > Settings > General > Webhooks URLs. 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.

2.2Webhook Payload Signing Mechanism

Warning

Important Update on Webhook Signing Mechanism:

We strongly recommend that you start integrating the new signing mechanism into your webhooks as soon as possible. This will ensure a smooth transition when the feature becomes mandatory. After the transition period, the previous webhook handling process will be gradually phased out.

Why We Have Implemented Webhook Payload Signing

In our continuous effort to uphold the highest standards of data security and integrity, we have implemented a robust payload signing mechanism for our webhooks. This approach is centered around the use of public and private key cryptography, combined with secure hashing algorithms, to authenticate and verify the data we send.

Here’s how this process enhances the security and reliability of our webhooks:

  1. Webhook Encryption Key Pair Generation and Management:

    • We generate a cryptographic key pair consisting of a private and a public key. The private key, securely stored in our database, is used to sign the webhook payloads. The public key is shared with you to enable the verification of these signatures and can be retrieved via uniquely generated keyId using read endpoint in the Webhook Encryption Service.

  2. Signing Process:

    • Each time a webhook payload is dispatched, we first hash the payload using the SHA-256 hashing algorithm, complemented by the Elliptic Curve Digital Signature Algorithm (ECDSA), to create a distinct and secure representation of the payload’s content. This hash is then encrypted with our private key, forming a digital signature. This digital signature is crucial for ensuring the payload’s integrity and authenticity. We then add this signature to the webhook’s outgoing HTTP request in the form of a custom header named x-signature. The value of this header includes essential details such as the algorithm used (SHA256withECDSA), a unique key identifier (keyId), and the actual signature. This header plays a vital role in enabling the recipient of the webhook to verify the authenticity of the received data by using the provided information, ensuring that the payload is indeed from a trusted source and has not been altered in transit.

  3. Secure Payload Transmission:

    • The payload, along with its digital signature, is transmitted to you. This process ensures that the payload reaches you exactly as we sent it, free from tampering or unauthorized modifications.

  4. Verification by Customers:

    • Upon receiving a webhook payload, you can verify its authenticity and integrity. By hashing the payload using the same method and decrypting the signature with the retrieved public key, you can confirm if the payload is legitimate and unaltered. A match between your computed hash and the decrypted signature indicates that the payload is authentic and was indeed sent from our system.

    • The process of verifying the authenticity and integrity of the received webhook payload is conducted programmatically through our SDK. Upon receipt of a webhook payload, your application can employ the provided SDK methods to validate the payload.

Transaction request header example:
"x-signature": "algorithm=SHA256withECDSA, keyId=2dcd5b38-78a1-47ea-a1c7-ed760403d88c, signature=jXt3fB8v7v/ea2MGUXj+c+FCUF6su51lCnH1DK/0tm444f6508K8FGtAFqVAmH/faJnzvE1IxLtcR6sj8M9b0g=="

2.3Webhook Listeners

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 > Settings > General > Webhook Listeners.

You can also programmatically create a listener using our API or SDK: example here.

2.4Invocations

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.

Transaction request example:
{
    "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.

Note
 We recommend the use of HTTP(s), i.e. an encrypted connection, if you intend to use the digitally signed payload, explained above.

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.

4Integration Details with Webhook Payload Signing Mechanism enabled

The HTTP request which is sent for a state change of an entity now includes an additional field state, which provides information about the update of the monitored entity’s state. This enhancement is a result of the implementation of our webhook encryption mechanism.

Payload field state provides direct information about the state update of the entity, making additional API calls to retrieve the entity state redundant.

Transaction request example:
{
    "eventId": 138833842,
    "entityId": 63762876,
    "listenerEntityId": 1472041829003,
    "listenerEntityTechnicalName": "Transaction",
    "spaceId": 30140,
    "webhookListenerId": 285874,
    "timestamp": "2022-08-23T14:20:53+0000",
    "state": "PROCESSING"
}

With the introduction of the state field, once you receive the notification at your endpoint, the need to make additional API calls to our system to read the state of the changed entity is greatly reduced. This enhancement not only streamlines the process but also maintains security by minimizing the exchange of sensitive data.

5Firewall 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 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.

5.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.211.247.160
  • 52.211.171.77
  • 52.211.239.229
  • 52.211.209.173
  • 52.208.210.84
  • 52.212.109.85
  • 52.210.89.1
  • 52.212.185.152
  • 52.212.192.130