2021-07-28 15:20:06 +00:00
|
|
|
# gohookr
|
|
|
|
|
2021-07-29 08:41:24 +00:00
|
|
|
A _really_ simple webhook receiver, which listens at `/webhooks/<webhook-name>`.
|
2021-07-28 15:20:06 +00:00
|
|
|
|
2021-07-29 07:43:06 +00:00
|
|
|
## Installation
|
|
|
|
|
|
|
|
After you [install go](https://golang.org/doc/install):
|
|
|
|
|
|
|
|
```
|
2021-08-04 09:22:19 +00:00
|
|
|
make
|
2021-07-29 07:43:06 +00:00
|
|
|
```
|
|
|
|
|
2022-02-12 13:27:58 +00:00
|
|
|
## Configuration
|
|
|
|
|
|
|
|
Default config path is `/etc/gohookr.json`.
|
|
|
|
It can be overriden by setting environment variable `CONFIG`.
|
|
|
|
|
|
|
|
Check below for an example configuration, which should tell you most of the things you need to know
|
|
|
|
to configure gohookr.
|
|
|
|
|
|
|
|
Currently gohookr must be restarted after config changes.
|
|
|
|
|
|
|
|
### Signature Verification
|
2021-07-29 06:35:16 +00:00
|
|
|
|
|
|
|
Signature verificaiton is done using SHA256 HMACs.
|
2021-07-29 06:44:14 +00:00
|
|
|
You **must** set which HTTP header gohookr will receive a signature from using the `SignatureHeader`
|
|
|
|
key for each service.
|
|
|
|
You should also specify a shared secret in the `Secret` key.
|
2021-07-29 06:35:16 +00:00
|
|
|
|
2021-08-04 20:43:37 +00:00
|
|
|
You may also need to specify a `SignaturePrefix`.
|
|
|
|
For GitHub it would be `sha256=`.
|
|
|
|
|
2022-02-12 13:27:58 +00:00
|
|
|
#### Disable Signature Verification
|
2021-07-29 06:35:16 +00:00
|
|
|
|
2021-08-14 00:02:36 +00:00
|
|
|
You can disable signature verification by setting `DisableSignatureVerification` for a service to `true`.
|
|
|
|
|
|
|
|
You can disable signature verification for all services by setting environment variable
|
2021-07-29 06:54:22 +00:00
|
|
|
`NO_SIGNATURE_VERIFICATION` to `true`.
|
2021-07-29 06:35:16 +00:00
|
|
|
|
2022-02-12 13:27:58 +00:00
|
|
|
### Writing Commands
|
2021-08-04 10:51:40 +00:00
|
|
|
|
|
|
|
gohookr doesn't care what the command is as long as the `Program` is executable.
|
|
|
|
You can specify extra arguments with the `Arguments` field.
|
2023-10-28 20:48:54 +00:00
|
|
|
You can ask it to put the payload as the last (or second to last if `AppendHeaders` is set) argument by setting `AppendPayload` to true.
|
|
|
|
You can ask it to put the request headers as the last argument by setting `AppendHeaders` to true.
|
2021-08-04 10:51:40 +00:00
|
|
|
|
2022-02-12 13:27:58 +00:00
|
|
|
### Writing Tests
|
2021-07-29 06:35:16 +00:00
|
|
|
|
|
|
|
gohookr can run test before running your script.
|
|
|
|
Tests must be in the form of bash scripts.
|
|
|
|
A non-zero return code is considered a fail and gohookr will run no further tests and will not
|
|
|
|
deploy.
|
|
|
|
|
|
|
|
Tests are run in the order they're listed so any actions that need to be done before
|
2021-08-04 10:51:40 +00:00
|
|
|
tests are run can simply be put in this section before the tests.
|
2021-07-29 06:44:14 +00:00
|
|
|
|
2022-02-12 13:27:58 +00:00
|
|
|
### Example Config
|
2021-07-29 06:44:14 +00:00
|
|
|
|
2021-07-29 08:41:24 +00:00
|
|
|
Required config keys are `ListenAddress` and `Services`.
|
|
|
|
|
2021-08-04 10:51:40 +00:00
|
|
|
Requried keys per service are `Script.Program`, `Secret`, `SignatureHeader`.
|
2021-07-29 08:41:24 +00:00
|
|
|
|
2021-07-29 06:44:14 +00:00
|
|
|
An example config file can be found [here](./config.json) but also below:
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
2021-07-29 08:41:24 +00:00
|
|
|
"ListenAddress": "127.0.0.1:8654",
|
2021-07-29 06:44:14 +00:00
|
|
|
"Services": {
|
|
|
|
"test": {
|
2021-08-04 10:51:40 +00:00
|
|
|
"Script": {
|
|
|
|
"Program": "./example.sh",
|
2023-10-28 21:41:38 +00:00
|
|
|
"AppendPayload": true,
|
|
|
|
"AppendHeaders": true
|
2021-08-04 10:51:40 +00:00
|
|
|
},
|
2021-08-14 00:02:36 +00:00
|
|
|
"DisableSignatureVerification": true,
|
2021-07-29 06:44:14 +00:00
|
|
|
"Tests": [
|
|
|
|
{
|
2021-08-04 10:51:40 +00:00
|
|
|
"Program": "echo",
|
|
|
|
"Arguments": [ "test" ]
|
2021-07-29 06:44:14 +00:00
|
|
|
}
|
|
|
|
]
|
2021-08-06 13:54:36 +00:00
|
|
|
},
|
|
|
|
"fails_tests": {
|
|
|
|
"Script": {
|
|
|
|
"Program": "./example.sh",
|
|
|
|
"AppendPayload": true
|
|
|
|
},
|
|
|
|
"Secret": "who_cares",
|
|
|
|
"SignatureHeader": "X-Hub-Signature-256",
|
|
|
|
"SignaturePrefix": "sha256=",
|
|
|
|
"Tests": [
|
|
|
|
{
|
|
|
|
"Program": "false",
|
|
|
|
"Arguments": []
|
|
|
|
}
|
|
|
|
]
|
2021-07-29 06:44:14 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|