A personal Node.js-based webhook server that executes TypeScript on-demand, with basic auth, Puppeteer for browser automation, and Errsole logging.

1. Fork it
2. Clone it

git clone https://github.com/selfagency/sandman.git

3. Install dependencies*

pnpm i

4. Build the server*

pnpm run build

5. Create a .env file in the project root and add a random value for LOG_KEY*

LOG_KEY="ye*@^nMGhLQMNun!s*PUnU^!HPrB*Ne2qeLZn^Ek!eZzgq5kjaPZfBL*r45JDqmR"

6. Duplicate config.example.toml and edit away!

cp config.example.toml config.toml
code config.toml

*Skip steps marked with an asterisk for Docker

1. Drop your TypeScript files in /scripts. If bare metal, you can install any dependencies directly into the repo. If Docker, using pre-bundled scripts or a Git submodule is recommended. Use the environment variable OUTDIR to specify a build folder if needed.
2. Add a corresponding block in config.toml where the block header is the name of the script file. Eg., if your script is named example.ts:

[example]
id = "8b9c92d5-6e61-4486-b6c8-04126dd40e09"   # Generate a UUID to serve as the URL
auth = false                                  # Set whether or not to use auth
password = "password"                         # Required if `auth` is true
js = false                                    # Required if file is JS, not TS

pnpm run start

Use the included docker-compose.yml or start up manually:

docker pull ghcr.io/selfagency/sandman:latest
docker run --name sandman \
  -e LOG_KEY=${LOG_KEY} \
  -v "$(pwd)/.env:/app/.env" \
  -v "$(pwd)/data:/app/data" \
  -v "$(pwd)/config.toml:/app/config.toml" \
  -v "$(pwd)/scripts:/app/scripts" \
  -p 3000:3000 \
  -p 8001:8001 \
  ghcr.io/selfagency/sandman:latest

curl -v \
 -X POST \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic ${BASE64_ENCODED_PASSWORD}" \
 -d "{ \"payload\": \"data\" }" \
 "http://localhost:3000/hooks/8b9c92d5-6e61-4486-b6c8-04126dd40e09"

A realtime logging console is provided via Errsole on port 8001. You'll be asked to create a username and password the first time you visit it.

A log function is provided in /scripts/common.ts to transmit log messages to Errsole.

1. Never commit your config.toml file, especially if it has passwords in it.
2. You should absolutely run this behind a reverse proxy (which will provide HTTPS) and a web application firewall to provide defense against malicious actors.
3. Be sure to secure both port 3000 and port 8001.