Webhooks Configuration

Configuration

Add new webhook

Webhook are managed in the BIP under Administration - Webhooks.

Please note that print-screens below are given as example. Correct data will need to be entered during configuration.

You can attach webhooks to each entity in the tree.
The effect of attaching a webhook to an entity is that you get notified of all events of the configured types for this entity and its descendants.

When you click the "Add new webhook" button you are presented with the following fields for configuring your webhook:

URL The URL that receives the notifications.
Notification types The notification types you want to subscribe to. E.g. by selecting PAYMENT the registered URL will receive all payment events happening on this entity and its descendants. You can choose any subset of the available options.
Fields to include The fields you want to receive in payload. E.g. by selecting ALL, payload will include every fields the transaction generates.
  • ALL Payload includes all fields the transaction generates
  • NON_CUSTOMER_DATA Payload includes only fields which are not customer data
Active Only an active webhook will receive notifications. A webhook can become inactive through this setting, by being unavailable for 5 days or by replying incorrectly to the notification.
Secret The secret is the key used for encrypting the message's content. The notification's header contains the initialization vector and authentication tag.
Wrapper If you need to get specific content type for webhooks, you can choose wrapper for it.
  • None No wrapper for webhook body. Content-Type will be text/plain and body will be (encrypted) hexadecimal string.
  • JSON Json wrapper for webhook body. Content-Type will be application/json and body will be wrapped by json
    example: {"encryptedBody":"[(encrypted) hexadecimal string]"}
Emails The email address where the daily statistic of failure notifications is sent to. This is optional, and the user can enter more than one email address.

Testing Webhooks

You can easily test your registered URL by clicking the Test-Button. The notification server then sends a message to the registered URL with dummy payment data.

This ensures that...

  • Your URL is correct
  • Your firewall-setup accepts our notification server
  • You can receive our messages
  • You can respond in the correct format

If the test service receives 200 OK as response to the notification, then Test will be changed to Success

Once the URL has been tested, real notifications can be sent by triggering the corresponding event on our system. For payments, this is as simple as sending a test payment transaction to one of the entities your webhook is listening to. This can be done with one click by using the Server-to-Server tutorial.

Even when your own server is not yet ready, you can use tools such as http://requestb.in (https://webhook.site/ seems to be working now) to easily generate a receiver URL and then analyze the message structure that was received. It is still completely secure, as the message bodies will be encrypted.

If your server failed to process/receive the notification message properly (or was down), the message will be retried for 30 days. The notifications that were queuing and being retried up to the last 30 days will be deleted. You still can get their content by using the other reporting tools of the platform. You will also receive a daily email with the top recent 100 failed transactions notifications on the emails you configured for this listenerwebhook.

Next