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​

  • Base path: The base path represents the root URL of your service, e.g. https://example.com. Based on this example URL, Banqup will send messages to the endpoint https://example.com/messages, which must be configured to accept POST requests.
  • Message category and type to which you are subscribing.

Step 1: Get ID of Message Listener extension point

Endpoint: GET/core/plugin/api/v1/extensionPoints


Request body: View documentation


Query parameter:

  • namespace: com.unifiedpost.btx
  • name: messageListeners
  • version: 1.0
curl -L 'https://{{serverURL}}/core/plugin/api/v1/extensionPoints?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: 


{
    "extensionPoints": [
        {
            "extensionPointId": "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 extension

Endpoint: POST/core/plugin/api/v1/extensionPoints/{extensionPointId}/extensions


Path parameter:

  • extensionPointId: Use the value returned in the previous response.

Request body: View documentation


curl -L 'https://{{serverURL}}/core/plugin/api/v1/extensionPoints/45e62b83-51e5-492c-b270-d1606c99fde6/extensions' \
-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: 


{
    "extensionId": "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: GET/core/plugin/api/v1/extensionPoints/{:extensionPointId}/extensions


Path parameter:

  • extensionPointId

Request body: View documentation


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

Successful response: 


{
    "extension": [
        {
            "extensionId": "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"
            }
        }
    ]
}