Configuration

Configuration

Last updated:April 11th, 2024

The webhooks are managed in the user interface portal under Administration > Webhooks.

  • They should be first configured and tested.
  • They can be created at any entity level.
  • The messages are filtered based on the configured notification types.
  • The messages are automatically retried when destination is not reachable.
  • The failed delivery of the messages trigger automatic daily email alerts.
Multiple webhook endpoints: The same notification will be delivered to multiple active webhook URLs configured up to the highest level in the entity tree.
Webhook endpoint scope: A webhook URL will receive notifications from the entity where it is configured down to the lowest level in the entity tree.

Add webhook

The following fields are to be configured for your webhook:

ParameterDescription
URL The public URL to receive the notifications.
Types The notification types to subscribe on the selected entity and its descendants:
  • PAYMENTS: All selected payment events
  • REGISTRATIONS: All selected token events
  • SCHEDULES: All selected payment scheduling events
  • RISKS: All selected risk events
You can choose any subset of the available options.
Fields The fields you want to receive in payload.
  • ALL: The webhook payload includes all fields the transaction generates
  • NON_CUSTOMER_DATA: The webhook payload includes only fields which are not customer data related
Secret The secret key to encrypt the payload.
Wrapper The wrapper to choose for the content type of the encrypted payload:
  • None: No wrapper for the webhook payload. Content-Type will be text/plain and the body will be (encrypted) hexadecimal string.
  • JSON: JSON wrapper for the webhook payload. Content-Type will be application/json and the body will be wrapped by json
    Example: {"encryptedBody":"[(encrypted) hexadecimal string]"}
Emails The multiple email addresses you can set to retrieve daily automated summary emails when the delivery of the notifications fail.

Webhook state

When first created the webhook URL is by default inactive. Before activating, the webhook URL must be tested. Forcing the activation it triggers sending a test notification to the configured webhook URL. The destination becomes active once a successful HTTP 200 message response is received for the test notification.

The webhook URL can be deactivated at any time. Once deactivated, no notification is going to be sent anymore to the configured destination. All the notifications that failed to be delivered in the past and queued for a retrial later will be purged.

Test webhook

You can test your configured webhook URL by using the Click to test feature. The notification server then sends a message to the registered URL with dummy transaction data.

This ensures that:

  • Your URL is correct
  • Your firewall setup accepts notifications from an external notification server
  • You receive the messages
  • You respond in the correct format

The test completes as successful if your server responds with a HTTP 200.

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.

See also