6. Webhooks

Breaking change

🚧

Removing PII data from notification webhook

As of October 1 2024, we will remove the PII and IVMS objects from the webhook data.

If you want to get the PII, it needs to be requested using txInfo instead.

Please see here for more details on txInfo and here if you are looking to implement name match

---

Current functionalities using Webhooks

Currently, Notabene allows VASPs to register Webhooks to offer the following functionalities:

• To notify about transaction state changes
• When to trigger the blockchain transaction

Both notification types are powered by the same Multi-Message Webhookthat can be setup using the UI as described below.

---

Multi-Message Webhook

Notabene has been working on supporting the registration of a single Multi-Message Webhook URL per VASP, improving the overall development experience:

• Less overhead on VASP's development teams: VASPs register a unique Webhook URL that will be invoked with different message types. The messages received depend on settings enabled by each VASP.
• Easier documentation on Webhooks: functionality changes will involve the addition of new message schemas or versions, without registering any additional Webhook URL, making it more future-proof.
• Better verification support: please have a look at this guide to read the recommendations on how to secure your Webhook in order to make sure that only Notabene (through SVIX) is invoking your Webhook.

---

Setup

In the Portal, as Admin user, go to Settings and open the Card for Multi-Message Webhook setup:

Toggle the button and the platform will load an embedded webhooks endpoint management and monitoring application.

Choose what events to subscribe

• haltBlockchainTransaction and processBlockchainTransaction are trigger webhook events type
• transactionUpdated are the notification webhook events type

You can set-up one or more endpoints, select the message types to be received and configure a few advanced options.

🚧

Note: the URL does not support specific port numbers

Once you save your 'Endpoint', double click to open it and navigate to the Advanced tab to find your 'signing secret' that you can use to verify the source is trusted. This follows the security recommendations from SVIX. Please make sure to implement their recommendations and never share the secret.

---

Troubleshooting

At any time you can enter this application in our portal and monitor the health of your endpoints. You can see the message attempts, the failures and if needed, you can resend or replay messages.

---

Webhook IP

Make sure that your Webhook is reachable by Notabene (through SVIX). The requests to your webhook will come from one of the IPs mentioned here under EU.

---

Retries / Disabled endpoint

See here for the retry schedule.

If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled and an operational webhook (EndpointDisabledEvent) will be sent to your account. The clock only starts after multiple deliveries failed within a 24 hour span, with at least 12 hours difference between the first and the last failure.