Using address webhook

This enables you to register a webhook that the Notabene system can query to check if the address belongs to you, and thereby speed up the response time by performing auto-confirmation/rejection and auto-redirect of your incoming travel rule transactions.

Register a webhook

You can register your address query webhook by calling POST integrations/{{vaspDID}}/address-query-webhook and in the payload you need to send a required field called url that should contain your webhook URL.

You can also add an optional field called params which you can fill in with whatever query parameters you also want use:

{
"url": "https://youraddresswebhookurl.com/notabenewebhook/",
"params": "?notabene-api-key=API-KEY"
}

If you want to update the webhook url or params, just register a webhook again.

The endpoint for registering a webhook will always return a secret that you need to store in order to validate our request later:

ac81032ad9a3f2cea504011c76fdb53ac5899371

Webhook request

When Notabene queries your webhook, we will use the URL + asset & address of the incoming transaction + the params that you have stored:

https://youraddress.com/notabenewebhook/?asset={{assetType}}&address={{destinationAddress}}&{{params}}

📘

Supported method

Your webhook URL needs to accept the GET HTTP method.

Validating Notabene's signature

Notabene's query will come with a signature inside a custom header called X-Notabene-Signature:

You can use the below JavaScript to validate the signature using the secret from when you registered the webhook:

js
const crypto = require('crypto');
const express = require('express')
const app = express()

const isValid = (request) => {
    const secret = process.env.NOTABENE_WEBHOOK_SECRET;
    const method = 'GET';
    const webhook = `${req.protocol}://${req.hostname}${req.originalUrl}`
    const params = request.params.toString();

    const signedRequest = crypto.createHmac('sha1', secret)
        .update(method + webhook + params)
        .digest('base64')
     // highlight-next-line
    return signedRequest === request.headers.get('X-Notabene-Signature');
}

app.get('/addressQuery', (req, res) => {
    const requestIsValid = isValid(req)
    // ...
})

Webhook response

To be able to process your response automatically, the webhook needs to return an object that looks like this:

js
{
    owns: true,         // A boolean that indicates if the VASP owns the address
    beneficiaryInfo: {} // (Optional) Beneficiary info that your VASP can share in IVMS101 format  
}

Delete a webhook

You can delete your address query webhook by calling DELETE integrations/{vaspDID}/address-query-webhook

The delete endpoint will return a boolean called isDeleted and a messageto indicate if the webhook was deleted or not.

IP address

If you want to set up security controls or need to whitelist, the webhook notifications will only be sent from the following IPs:

📘

IP addresses

PROD:
3.120.79.24

TEST:
3.120.226.248

If you confirm that the address is yours, the status of the travel rule message will change to "ACK" and the beneficiary/originator details will be made available to you.

The name of the originator is then processed by your sanctions screening provider and the originating wallet address by your blockchain analytics provider (if the integration with them is enabled in our marketplace).
If these integrations are not enabled, you can use the details pushed by the webhook instead to do this internally.