Skip to main content

Set up a message listener​


Messages are notifications sent to other listening components about actions performed on the Banqup platform. For example, several components might be interested to be notified when a new document has been uploaded: reconciliation, signing, accounting software etc.
Listening to messages requires registration of a "message-listening" plugin (predefined hook) within the platform. Also, because not all components are interested in all messages, you can filter what messages you want to receive, using message categories and types.

Check out the API guides for more information on plugins and messages and follow the steps below to set up a message listener.

Prerequisites​

Step 1: Get ID of Message Listener plugin interface

Endpoint: /core/plugin/v2/pluginInterfaces


Query parameters:

  • namespace: com.unifiedpost.btx
  • name: messageListeners
  • version: 1.0

View documentation


curl -L 'https://{{serverURL}}/core/plugin/v2/pluginInterfaces?namespace=com.unifiedpost.btx&name=messageListeners&version=1.0' \
-H 'Content-Type: application/json' \
-H 'Accept: application/x-ndjson' \
-H 'Authorization: Bearer YOUR TOKEN'

Successful response: 


{
    "pluginInterfaces": [
        {
            "pluginInterfaceId": "45e62b83-51e5-492c-b270-d1606c99fde6",
            "namespace": "com.unifiedpost.btx",
            "name": "messageListeners",
            "version": "1.0",
            "authorizationEndpoint": {
                "url": "http://{{serverURL}}/core/message/v1/hooks/messageListener"
            },
            "public": false
        }
    ]
}

Step 2: Register your Message Listener plugin

Endpoint: /core/plugin/v2/pluginInterfaces/{pluginInterfaceId}/plugins


Path parameter: pluginInterfaceId . Use the value returned in the previous response.


Request body: View documentation


curl -L 'https://{{serverURL}}/core/plugin/v2/pluginInterfaces/45e62b83-51e5-492c-b270-d1606c99fde6/plugins' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "data":{
        "basePath": "https://example.com",
        "authorizationHeader": "Bearer YOUR TOKEN",
        "filters": [
            {
                "type": "CATEGORY",
                "test": ["document"]
            },
            {
                "type": "TYPE",
                "test": ["com.unifiedpost.btx.data.events.v1.DocumentCreated"]
            }
        ]
    }
}'

Successful response: 


{
    "pluginId": "343cb028-d059-4bbd-834e-ca58c7f99c85",
    "authorizationInfo": {
        "filters": {}
    },
    "data": {
        "basePath": "https://example.com",
        "authorizationHeader": "Bearer YOUR TOKEN",
        "filters": [
            {
                "type": "com.unifiedpost.btx.data.events.v1.DocumentCreated",
                "category": "document"
            }
        ]
    }
}

From now on, you will receive messages of category "document" from Banqup, if they are of type "com.unifiedpost.btx.data.events.v1.DocumentCreated".

Step 3: View results

Endpoint: /core/plugin/v2/pluginInterfaces/{pluginInterfaceId}/plugins


Path parameter: pluginInterfaceId


Request body: View documentation


curl -L 'https://{{serverURL}}/core/plugin/v2/pluginInterfaces/45e62b83-51e5-492c-b270-d1606c99fde6/plugins' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR TOKEN' \

Successful response: 


{
    "plugin": [
        {
            "pluginId": "31f3b2a7-ccc9-40ff-bbbf-c876b9130784",
            "authorizationInfo": {
                "filters": {}
            },
            "data": {
                "filters": [
        {
            "type": "CATEGORY",
            "test": ["document"]
        },
        {
            "type": "TYPE",
            "test": ["com.unifiedpost.btx.data.events.v1.DocumentCreated"]
        }
                            ],
                "basePath": "https://example.com",
                "authorizationHeader": "Bearer YOUR TOKEN"
            }
        }
    ]
}