Webhooks

Current functionalities using Webhooks

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

• Register a Webhook for querying addresses
• To notify about transaction state changes

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.

Please note that the Multi-Message Webhook is not yet a replacement of the currently supported Webhook implementations.

Setup

• Register the Multi-Message Webhook URL:
  POST on /webhook with the following payload to register your Multi-Message Webhook:
  • JSON

      {
          "vaspDID": "your VASP did goes here",
          "url": "the URL to register as your Multi-Message Webhook"
      }
    

    DELETE on /webhook to unregister a previously registered Multi-Message Webhook.
  • JSON

    {
        "vaspDID": "your VASP did goes here"
    }
    

• Make sure that your Webhook is reachable by Notabene (through SVIX). The whitelist of IP addresses can be found here.
• Make sure that your Webhook is secure by following the security recommendations from SVIX.
• Refer to the following section Supported messages to better understand when Notabene will call your Webhook.

Supported messages

Notabene will call your Webhook with the following messages below. Please be aware that some messages could be sent more than once with the same payload, depending on specific use cases. Make sure you are controlling that on your end.

Message 'notification.processBlockchainTransaction'

• Notabene will send this message when the Transaction has reached the state in which the blockchain transaction can be done. The trigger state is meant to be set by via the setting statusToProcessBlockchain ("CREATED", "SENT", "ACK", "ACCEPTED" or null) or manually by Compliance Officers from the Dashboard (under Settings)
• The message will contain the full Transaction Object (same object returned by /tx/create or /tx/info).

{
  "message": "notification.processBlockchainTransaction",
  "payload": {
    "transaction": "..."
  },
  "version": "1.0.0"
}

Message 'notification.haltBlockchainTransaction'

• This message is complementary to the notification.processBlockchainTransaction one, as it depends on the same setting statusToProcessBlockchain to be implicitly enabled.
• Notabene will send this message when the Transaction has reached the state in which the blockchain transaction needs to be halted. The states triggering this notification are: "CANCELLED", "REJECTED" and "DECLINED".
• The message will contain the full Transaction Object (same object returned by /tx/create or /tx/info).

{
  "message": "notification.haltBlockchainTransaction",
  "payload": {
    "transaction": "..."
  },
  "version": "1.0.0"
}