# aries-cloudagent-webhook-relay

**Repository Path**: paradis3/aries-cloudagent-webhook-relay

## Basic Information

- **Project Name**: aries-cloudagent-webhook-relay
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-03-19
- **Last Updated**: 2021-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hyperledger Aries Cloud Agent - Webhook Relay

The [Hyperledger Aries Cloud Agent - Python (ACA-Py)](https://github.com/hyperledger/aries-cloudagent-python) currently requires the ACA-Py controller to host several webhook endpoints in order to receive updates about the agents state as described [here](https://github.com/hyperledger/aries-cloudagent-python/blob/01fc73be644439fa27ab43089353859f08517ba2/AdminAPI.md). 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

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

> See the [aries-cloudagent-ula-development-setup](https://github.com/ula-aca/aries-cloudagent-ula-development-setup) repository for a docker-compose example of the webhook-relay with [ACA-Py](https://github.com/hyperledger/aries-cloudagent-python/) and [von-network](https://github.com/bcgov/von-network).

### Manual

```bash
# 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:

```bash
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:

```jsonc
{
  "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.