Hyperledger Aries Cloud Agent - Webhook Relay

The Hyperledger Aries Cloud Agent - Python (ACA-Py) currently requires the ACA-Py controller to host several webhook endpoints in order to receive updates about the agents state as described here. This introduces a problem for mobile ACA-Py controller clients since it is not possible to expose such endpoints.

This repository aims to solve this problem 'the dirty way' by placing another component (called webhook-relay) in between ACA-Py and the controller. The webhook-relay exposes the required webhook endpoints and stores the webhook requests made by ACA-Py in an in-memory FIFO queue. The controller can then fetch the messages either by polling, or by connecting to the websocket interface. All messages are stored in memory. Once a message has been picked up by the controller (regardless if it's by polling or websocket) the message is removed from memory and will no longer be available.

Setup

Docker

docker build -t webhook-relay .
docker run -p 8080:8080 webhook-relay

See the aries-cloudagent-ula-development-setup repository for a docker-compose example of the webhook-relay with ACA-Py and von-network.

Manual

# make sure you have virtualenv
pip install virtualenv # or pip3 install virtualenv

# create a virtual environment
virtualenv --python=python3.7 ./webhook-relay-env

# load it
source ./webhook-relay-env/bin/activate

# install dependencies
pip install -r requirements.txt

Usage

usage: webhook-relay [-h] [-l {CRITICAL,ERROR,WARNING,INFO,DEBUG}]
                        [--api-key API_KEY] [--insecure-mode] [--host HOST]
                        [--port PORT]

collects and cache's aca-py webhook calls until requested by controller.

optional arguments:
  -h, --help            show this help message and exit
  -l {CRITICAL,ERROR,WARNING,INFO,DEBUG}, --log {CRITICAL,ERROR,WARNING,INFO,DEBUG}
                        the log level
  --api-key API_KEY     if passed, this will be used as the API key (one will
                        be generated by default).
  --insecure-mode       if passed, no API key will be generated and the --api-
                        key flag will be ignored.
  --host HOST, -H HOST  the host the relay will run on
  --port PORT, -p PORT  the port the relay will run on

Connecting ACA-py to the webhook-relay

When you run the webhook-relay, it will print the following message:

INFO - log level: INFO
INFO - both the --api-key and --insecure-mode flags are not provided
INFO - generated api key: 039372a9-cc60-4c71-9fde-b5848a9ac9e2
INFO - ws exposed at: ws://0.0.0.0:8080/ws
======== Running on http://0.0.0.0:8080 ========
(Press CTRL+C to quit)

Copy the printed address (in this case http://0.0.0.0:8080) and pass it to a ACA-Py instance as the --webhook-url argument. All webhook requests made by ACA-Py will now be directed towards the webhook-relay.

Getting the messages

The controller can fetch the messages in two ways:

Polling

It can poll the messages by periodically making a request to http://0.0.0.0:8080/new_messages. This will return all the messages that the webhook-received since the last polling request. When using the polling method in secure mode you a Bearer authorization header is required in each polling request providing the api key printed in the relay's logs.

Websocket

For realtime message updates, you can subscribe to the websocket interface at http://0.0.0.0:8080/ws. When the controller connects to the websocket interface, the webhook-relay will wait for the controller to send an initial message to kick things off. This message should contain a stringyfied json object that looks like this:

{
  "fastForward": true, // required
  "auth": "your api key" // only required when running in secure mode
}

When fastForward is set to true, the webhook-relay will start streaming all the messages it has in queue until the queue is empty. After that it will forward incoming webhook requests directly to the controller as long as the connection stays open. Upon disconnect it will start queueing the incoming messages once again, until the next connection opens. This way the controller can 'update' its state in case of connection trouble and won't miss a single message. When fastForward is set to false it will simply clear the entire queue and only forward new incoming webhook requests that are made after the connection is opened.

The auth key is only required in secure mode and should contain the api key that is printed to the logs.