gpio-webhook-server/readme.md

# A simple webhook server for smartswitch devices

This is a tiny webserver designed to receive webhooks that control
microcontrollers running [smartswitch](https://git.annabunch.es/annabunches/smartswitch/).

## Configuration

The server can be configured via the following environment variables:

* DEBUG - if set, extra output will be logged / generated. **this will leak secrets to stdout**
* LISTEN_PORT - the TCP port to serve the app on. Default is `7200`.
* WEBHOOK_CONFIG_FILE - location of the webhook config. Defaults to `./webhooks.yaml`.

The webhooks configuration file should be an array of entries with the following keys:

* name - A human-readable name that explains the webhook's purpose.
* path - The webhook will be served by the app at this path. **Treat this as a secret value.**
* num_switches - the number of data points / indexes expected with each POST.
* momentary_switches - an array of any indexes that refer to 'momentary' switches.  
  The value of these indexes will be reset to 0 after the next GET request to the webhook.

## Build & Run

Build the server with:

```
make build
```

And run with:

```
./smartswitch-server
```

A dockerfile is also included, along with a sample docker-compose.yml demonstrating
how the server might be run in a containerized environment.

Note that you SHOULD always run this service behind a TLS-encrypted proxy. Using plain http WILL expose your secrets.


## Usage

To read the current webhook data, simply send a GET to the webhook URL, with the `key` parameter appropriately set. Example:

```
curl -x GET "https://example.com/WEBHOOK_PATH
```

To write data, send a POST to the same URL, with a json-formatted body in the following format:

```
[value0, value1, value2, ...]
```


## Future Development

* Use a more robust secret than "the URL is hidden behind TLS." Maybe client-side x509 certs.