Webhooks Configuration

Error message

Tutorial tokenization is unknown


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 more than 24h 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]"}

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.