56 lines
1.8 KiB
Markdown
56 lines
1.8 KiB
Markdown
|
# 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.
|
||
|
|
* secret_key - An authentication value for reading and writing to the webhook. This must be included in all requests. (see Usage for format)
|
||
|
|
* 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 secret keys.
|
||
|
|
|
||
|
|
|
||
|
|
## 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?key=WEBHOOK_KEY
|
||
|
|
```
|
||
|
|
|
||
|
|
To write data, send a POST to the same URL, with a json-formatted body in the following format:
|
||
|
|
|
||
|
|
```
|
||
|
|
[value0, value1, value2, ...]
|
||
|
|
```
|