{"id":17084134,"url":"https://github.com/nukesor/pueue-webhook-server","last_synced_at":"2025-04-12T21:12:28.787Z","repository":{"id":44692827,"uuid":"319792335","full_name":"Nukesor/pueue-webhook-server","owner":"Nukesor","description":"A webhook server that schedules commands on request. Uses Pueue as executor backend.","archived":false,"fork":false,"pushed_at":"2025-04-03T16:01:41.000Z","size":391,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-12T21:12:22.171Z","etag":null,"topics":["continuous-deployment","hacktoberfest","pueue","server","webhook"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nukesor.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-09T00:00:40.000Z","updated_at":"2025-04-11T20:22:12.000Z","dependencies_parsed_at":"2024-06-02T12:31:09.340Z","dependency_job_id":"a6366f39-6bf1-4504-9c0e-7f62918534a8","html_url":"https://github.com/Nukesor/pueue-webhook-server","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nukesor%2Fpueue-webhook-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nukesor%2Fpueue-webhook-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nukesor%2Fpueue-webhook-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nukesor%2Fpueue-webhook-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nukesor","download_url":"https://codeload.github.com/Nukesor/pueue-webhook-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631681,"owners_count":21136562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["continuous-deployment","hacktoberfest","pueue","server","webhook"],"created_at":"2024-10-14T13:05:45.362Z","updated_at":"2025-04-12T21:12:28.774Z","avatar_url":"https://github.com/Nukesor.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pueue Webhook Server\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n\nThis little helper serves a simple purpose: Execute commands on your server on incoming http requests.\nIt has been designed for continuous integration and supports Github's webhooks out of the box.\n\nThis project is mostly used by myself. You may also use it if you like.\nHowever, I don't plan to provide the same level of support for this project as I do for my other projects.\n\nWebhook-Server works in conjunction with [Pueue](https://github.com/nukesor/pueue), which allows easy output inspection, loggin and debugging of your webhook calls.\n\n**Example applications:**\n\n- Continuous integration for projects (Supports Github's webhooks).\n- On-Demand execution of parallel load-heavy tasks.\n- Trigger tasks on your server via a browser.\n- Trigger tasks between servers with a minimal setup.\n\nTake a look at the example config file [webhook_server.yml](https://github.com/Nukesor/pueue-webhook-server/blob/master/webhook_server.yml).\n\n## Installation\n\n**Manual installation:**\n\n```bash\ngit clone https://github.com/nukesor/pueue-webhook-server\ncd pueue-webhook-server\ncargo install --locked --path .\n```\n\nYour `$CARGO_HOME/bin` folder should be in your $PATH.\n\n## Configuration\n\nWebhook-Server is configured via files in this order:\n\n- `/etc/webhook_server.yml`\n- `~/.config/webhook_server.yml`\n- `./webhook_server.yml`\n\nConfig values of higher hierarchy config files are overwritten by lower hierarchy config files. E.g. a value in `/etc/webhook_server.yml` can be overwritten by `~/.config/webhook_server.yml`.\n\n### Config values\n\n- `domain (127.0.0.1)` The domain the server should listen on\n- `port (8000)` The port the server should listen on\n- `secret (null)` A secret for authentication via payload signature verification. Check the `Building a request` section for more information on signature headers. Can be, for instance, be created with `pwgen 25 1`\n- `ssl_private_key (null)` Path to SSL private key. The server will use it's own ssl certificate. Recommended, if you aren't using a proxy webserver, that already uses SSL. Using any kind of SSL is highly recommended, especially if you publicly expose your endpoint.\n- `ssl_cert_chain (null)` Path to SSL cert. Also required for SSL setup.\n- `basic_auth_user (null)` Your user if you want to do basic auth. Check the `Building a request` section for more information on basic_auth headers\n- `basic_auth_password (null)` Your password if you want to do basic auth.\n- `basic_auth_and_secret (false)` By default it's only required to authenticate via BasicAuth OR signature authentication. If you want to be super safe, set this to true to require both.\n- `pueue_port (6924)` Set this to the port your local pueue instance listens on.\n- `pueue_unix_socket (null)` In case you're using unix sockets, set this to your Pueue's socket path and `pueue_port` to `null`.\n- `pueue_directory` The working directory of Pueue, can be found in Pueue's configuration file.\n- `webhooks` A list of webhooks. The whole thing looks pretty much like this:\n\n```yaml\nwebhooks:\n  - name: \"ls\"\n    command: \"/bin/ls {{param1}} {{param2}}\"\n    cwd: \"/home/user\"\n    pueue_group: \"webhook\"\n```\n\n**Webhook config values**\n\n- `name` The name of the webhook, also the endpoint that's used to trigger the webhooks. E.g. `localhost:8000/ls`.\n- `command` The command thats actually used. If you want to dynamically build the command, you can use templating parameters like `{{name_of_parameter}}`.\n- `cwd` The current working directory the command should be executed from.\n- `pueue_group` Which pueue group should be used for this webhook.\n\n## Misc files\n\nThere are some template files for your setup in the [misc folder](https://github.com/Nukesor/pueue-webhook-server/tree/master/misc) of the repository.\nThese include:\n\n- A nginx proxy route example\n- A systemd service file\n\nIf you got anything else that might be useful to others, feel free to create a PR.\n\n## Github Webhook Setup\n\nGo to your project's settings tab and select webhooks. Create a new one and set these options:\n\n- Content-Type: Json\n- Secret: Same string as in your config\n- Enable SSL verification: Recommended, if you have any kind of SSL\n- Just the push event (The payload isn't used anyway)\n\nYou can click on the `Recent Deliveries` to redeliver any sent webhook, in case you want to debug your setup.\n\n## Building a request\n\nWebhook server accepts JSON POST requests and simple GET requests.\n\nThis is an example POST request issued with `httpie` and a secret of `72558847d57c22a2f19d711537cdc446` and `test:testtest` basic auth credentials:\n\n```bash\necho -n '{\"parameters\":{\"param1\":\"-al\",\"param2\":\"/tmp\"}}' | http POST localhost:8000/ls \\\n        Signature:'sha1=d762407ca7fb309dfbeb73c080caf6394751f0a4' \\\n        Authorization:'Basic dGVzdDp0ZXN0dGVzdA=='\n```\n\nIf you don't need templating, you can send a simple GET request:\n\n```bash\nhttp GET localhost:8000/ls Authorization:'Basic dGVzdDp0ZXN0dGVzdA=='\n```\n\n**Payload:**\n\nThe payload is a simple JSON object, with a single entry `parameters`.\nThis object contains all parameters necessary for rendering the template.\nIf no templating is needed, you can provide an empty object as payload or simply call the route via `GET`.\n\nFor instance, the payload for the command `'/bin/ls {{param1}} {{param2}}'` could look like this:\n\n```json\n{\n  \"parameters\": {\n    \"param1\": \"-al\",\n    \"param2\": \"/tmp\"\n  }\n}\n```\n\nThis would result in the execution of `ls -al /tmp` by the server.\n\n**Headers:**\n\n- `Authorization`: If `basic_auth_username` and `basic_auth_password` is specified, this should be the standard `Basic` base64 encoded authorization header. [Basic Auth guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)\n- `Signature:` If you specify a secret, the content of the signature is the HMAC of the json payload with the UTF8-encoded secret as key.\n  This procedure is based on Github's webhook secret system. (Github tells you to use a hex key, but they interpret it as UTF8 themselves -.-)\n  Python example: `hmac.new(key, payload, hashlib.sha1)`\n  Ruby example: `OpenSSL::HMAC.hexdigest(\"SHA1\", key, payload)`\n  [Github guide](https://developer.github.com/webhooks/securing/)\n- `X-Hub-Signature`: If there is no `Signature`, this header will be used for the signature check (to support Github's webhooks).\n\n## Security\n\n**Code injection:**\nWhen compiling dynamic commands with templating, you make yourself vulnerable to code injection, since the compiled commands are executed by the system shell.\nIf you plan on using templating and publicly exposing your service, please use some kind of authentication.\n\n1. You can use a secret to verify the payload with a signature (Github's authentication method). Anyway, this method is a bit annoying to implement, if you write your own implementation.\n2. You can use basic auth.\n3. If you want to be super safe, you can require both authentication methods.\n\n**SSL:**\nEspecially when using Basic Auth or templating it's highly recommended to use SSL encryption.\nThis can be either done by your proxy web server (nginx, apache, caddy) or directly in the application.\nOtherwise your credentials or your template payload could leak to anybody listening.\n\nAn example cert and key can be created like this `openssl req -nodes -new -x509 -keyout test.pem -out test.pem`.\nIf you need a password input for the private key, please create an issue or PR (much appreciated).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnukesor%2Fpueue-webhook-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnukesor%2Fpueue-webhook-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnukesor%2Fpueue-webhook-server/lists"}