Skip to content

Commit 9519941

Browse files
GrantBirkiGrantBirki
authored
Merge pull request #13 from github/docs
Docs
2 parents b325221 + 0ab2ae0 commit 9519941

File tree

4 files changed

+338
-3
lines changed

4 files changed

+338
-3
lines changed

‎CONTRIBUTING.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Contributing
2+
3+
Thank you for your interest in contributing to the Hooks gem! This document outlines how to contribute to the project, including setting up your development environment, running tests, and releasing new versions.
4+
5+
## Getting Started
6+
7+
To get your development environment set up, you simply need to run the following command:
8+
9+
```bash
10+
script/bootstrap
11+
```
12+
13+
> Note: This command assumes you have a Ruby version manager like `rbenv` installed.
14+
15+
## Running Tests
16+
17+
After writing some code or making changes, you will need to run the following commands to ensure everything is working correctly:
18+
19+
1. Run unit tests:
20+
21+
```bash
22+
script/test
23+
```
24+
25+
2. Run integration tests:
26+
27+
```bash
28+
script/integration
29+
```
30+
31+
3. Run acceptance tests:
32+
33+
```bash
34+
script/acceptance
35+
```
36+
37+
## Linting and Formatting
38+
39+
This project also requires that the linter must be run and pass before any code is committed. You can run the linter with the following command (with autocorrect enabled):
40+
41+
```bash
42+
script/lint -A
43+
```
44+
45+
## Releasing a new version
46+
47+
1. Update [`lib/hooks/version.rb`](lib/hooks/version.rb) with the next version number
48+
2. Run `bundle install` to update gem version contained in the lockfile
49+
3. Commit your changes and open a pull request
50+
4. When the pull request is approved and merged into `main`, the [`.github/workflows/release.yml`](.github/workflows/release.yml) workflow will automatically run to release the new version to RubyGems and GitHub Packages 🎉.

‎README.md‎

Lines changed: 286 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,292 @@
44
[![test](https://github.com/github/hooks/actions/workflows/test.yml/badge.svg)](https://github.com/github/hooks/actions/workflows/test.yml)
55
[![lint](https://github.com/github/hooks/actions/workflows/lint.yml/badge.svg)](https://github.com/github/hooks/actions/workflows/lint.yml)
66
[![integration](https://github.com/github/hooks/actions/workflows/integration.yml/badge.svg)](https://github.com/github/hooks/actions/workflows/integration.yml)
7+
[![release](https://github.com/github/hooks/actions/workflows/release.yml/badge.svg)](https://github.com/github/hooks/actions/workflows/release.yml)
78

8-
A Pluggable Webhook Server Framework written in Ruby
9+
A Pluggable Webhook Server Framework written in Ruby.
910

1011
![hooks](docs/assets/hooks.png)
12+
13+
## About ⭐
14+
15+
Hooks is a RESTful webhook server framework written in Ruby. It is designed to be simple, flexible, and extensible, allowing you to easily create and manage webhook endpoints for your applications. Hooks is designed to consolidate and process incoming webhook requests in a single place, making it easier to handle webhooks from multiple sources.
16+
17+
**Why Hooks?**: If you have to handle webhooks from multiple sources, you might end up with a lot of code that is similar but not quite the same. Hooks allows you to define a set of common behaviors and then extend them with plugins, so you can handle webhooks in a consistent way across your application.
18+
19+
## Features 🚀
20+
21+
- **Pluggable Architecture**: Easily extend the functionality of your webhook server with plugins for authentication, handlers, and more.
22+
- **Flexible Configuration**: Customize your webhook server via a simple configuration file, or programmatically with pure Ruby.
23+
- **Built-in Auth Plugins**: Support for common authentication methods like HMAC, shared secrets, and more.
24+
25+
## How It Works 🔧
26+
27+
Hooks is designed to be very easy to setup and use. It provides a simple DSL for defining webhook endpoints and then you can use plugins to handle the incoming requests and optionally authenticate them.
28+
29+
Here is a very high-level overview of how Hooks works:
30+
31+
1. You define a global configuration file (e.g. `hooks.yml`) where you can specify where your webhook endpoint configs are located, and the directory where your plugins are located. Here is an example of a minimal configuration file:
32+
33+
```yaml
34+
# file: hooks.yml
35+
handler_plugin_dir: ./plugins/handlers
36+
auth_plugin_dir: ./plugins/auth
37+
endpoints_dir: ./config/endpoints
38+
39+
log_level: debug
40+
41+
root_path: /webhooks
42+
health_path: /health
43+
version_path: /version
44+
45+
environment: development
46+
```
47+
48+
2. Then in your `config/endpoints` directory, you can define all your webhook endpoints in separate files. Here is an example of a simple endpoint configuration file:
49+
50+
```yaml
51+
# file: config/endpoints/hello.yml
52+
path: /hello
53+
handler: MyCustomHandler # This is a custom handler plugin you would define in the plugins/handlers directory
54+
```
55+
56+
3. Now create a corresponding handler plugin in the `plugins/handlers` directory. Here is an example of a simple handler plugin:
57+
58+
```ruby
59+
# file: plugins/handlers/my_custom_handler.rb
60+
class MyCustomHandler < Hooks::Plugins::Handlers::Base
61+
def call(payload:, headers:, config:)
62+
# Process the incoming webhook - optionally use the payload and headers
63+
# to perform some action or validation
64+
# For this example, we will just return a success message
65+
{
66+
status: "success",
67+
handler: "MyCustomHandler",
68+
payload_received: payload,
69+
timestamp: Time.now.iso8601
70+
}
71+
end
72+
end
73+
```
74+
75+
That is pretty much it! Below you will find more detailed instructions on how to install and use Hooks, as well as how to create your own plugins. This high-level overview should give you a good idea of how Hooks works and how you can use it to handle webhooks in your applications. You may also be interested in using your own custom authentication plugins to secure your webhook endpoints, which is covered in the [Authentication](#authentication) section below.
76+
77+
## Installation 💎
78+
79+
You can download this Gem from [GitHub Packages](https://github.com/github/hooks/pkgs/rubygems/hooks-ruby) or [RubyGems](https://rubygems.org/gems/hooks-ruby)
80+
81+
Via a Gemfile:
82+
83+
```ruby
84+
source "https://rubygems.org"
85+
86+
gem "hooks-ruby", "~> X.X.X" # Replace X.X.X with the latest version
87+
```
88+
89+
Once added to your Gemfile, run:
90+
91+
```bash
92+
bundle install
93+
```
94+
95+
## Usage 💻
96+
97+
### Basic
98+
99+
Here is a simple example of how to set up a Hooks server.
100+
101+
First, create a `config.ru` file:
102+
103+
```ruby
104+
# file: config.ru
105+
require "hooks-ruby"
106+
107+
# See the config documentation below for the full list of available options
108+
# For this example, we will just set use_catchall_route to true
109+
config = {
110+
use_catchall_route: true # will use the DefaultHandler for /webhooks/* - just an example/demo
111+
}
112+
113+
# Builds the Hooks application with the provided configuration
114+
app = Hooks.build(config: config)
115+
116+
# Run the Hooks application when the server starts
117+
run app
118+
```
119+
120+
Run the hooks server via puma which is the recommended server for Hooks:
121+
122+
```bash
123+
bundle exec puma --tag hooks
124+
```
125+
126+
Send a webhook request to the server in a separate terminal:
127+
128+
```bash
129+
curl --request POST \
130+
--url http://0.0.0.0:9292/webhooks/hello \
131+
--header 'content-type: application/json' \
132+
--data '{}'
133+
134+
# => { "message": "webhook processed successfully", "handler": "DefaultHandler", "timestamp": "2025-06-10T23:15:07-07:00" }
135+
```
136+
137+
Congratulations! You have successfully set up a basic Hooks server which will listen to anything under `/webhooks/*` and respond with a success message.
138+
139+
Keep reading to learn how to customize your Hooks server with different plugins for handlers, authentication, and more.
140+
141+
### Advanced
142+
143+
This section will go into a more advanced and detailed example of how to setup a Hooks server with custom plugins, authentication, and more. This section also assumes you already have the `hooks-ruby` gem installed via a bundler Gemfile as shown in the [Installation](#installation-) section above.
144+
145+
Before we get into the details, here is a high-level overview of the steps involved:
146+
147+
1. **Define your configuration**: Create a `hooks.yml` file to define your global configuration, including the directories for your plugins and endpoints.
148+
2. **Create your endpoint configurations**: Define your webhook endpoints in the `config/endpoints` directory, specifying the path and the handler plugin to use.
149+
3. **Implement your handler plugins**: Create custom handler plugins in the `plugins/handlers` directory to process incoming webhook requests.
150+
4. **Implement authentication plugins (optional)**: If you want to secure your webhook endpoints, create custom authentication plugins in the `plugins/auth` directory. Note that you might just be able to get away with using the built-in authentication plugins ([`hmac`](lib/hooks/plugins/auth/hmac.rb), or [`shared_secret`](lib/hooks/plugins/auth/shared_secret.rb)) for most use cases.
151+
152+
This example will assume the following directory structure:
153+
154+
```text
155+
├── config/
156+
│ ├── hooks.yml # global hooks config
157+
│ ├── puma.rb # puma config
158+
│ └── endpoints/
159+
│ ├── hello.yml
160+
│ └── goodbye.yml
161+
└── plugins/
162+
├── handlers/ # custom handler plugins
163+
│ ├── hello_handler.rb
164+
│ └── goodbye_handler.rb
165+
└── auth/
166+
└── goodbye_auth.rb # custom auth plugin (optional)
167+
```
168+
169+
Let's go through each step in detail.
170+
171+
#### 1. Define your global Hooks configuration
172+
173+
First, create a `hooks.yml` file in the `config` directory. This file will define your global configuration for the Hooks server, including the directories for your plugins and endpoints. Here is an example of a minimal configuration file:
174+
175+
```yaml
176+
# file: config/hooks.yml
177+
handler_plugin_dir: ./plugins/handlers
178+
auth_plugin_dir: ./plugins/auth
179+
180+
# Available endpoints
181+
# Each endpoint configuration file should be placed in the endpoints directory
182+
endpoints_dir: ./config/endpoints
183+
184+
log_level: debug
185+
186+
# Path configuration
187+
root_path: /webhooks # Base path for all webhook endpoints (e.g. /webhooks/hello)
188+
health_path: /health
189+
version_path: /version
190+
191+
# Runtime behavior
192+
environment: development # or production
193+
```
194+
195+
#### 2. Create your endpoint configurations
196+
197+
Endpoint configurations are defined in the `config/endpoints` directory. Each endpoint configuration file should specify the path for the webhook endpoint and the handler plugin to use. Here is an example of two endpoint configuration files:
198+
199+
> Note: You can also define auth plugins for each endpoint if you want to secure them. For this example, the `/hello` endpoint will not have authentication, while the `/goodbye` endpoint will use a custom authentication plugin.
200+
201+
```yaml
202+
# file: config/endpoints/hello.yml
203+
path: /hello # becomes /webhooks/hello based on the root_path in hooks.yml
204+
handler: HelloHandler # This is a custom handler plugin you would define in the plugins/handlers
205+
```
206+
207+
```yaml
208+
# file: config/endpoints/goodbye.yml
209+
path: /goodbye # becomes /webhooks/goodbye based on the root_path in hooks.yml
210+
handler: GoodbyeHandler # This is another custom handler plugin you would define in the plugins/handlers
211+
212+
auth:
213+
type: Goodbye # This is a custom authentication plugin you would define in the plugins/auth
214+
secret_env_key: GOODBYE_API_KEY # the name of the environment variable containing the secret
215+
header: Authorization
216+
```
217+
218+
#### 3. Implement your handler plugins
219+
220+
Create custom handler plugins in the `plugins/handlers` directory to process incoming webhook requests. Here is an example of a simple handler plugin for the `/hello` endpoint:
221+
222+
```ruby
223+
# file: plugins/handlers/hello_handler.rb
224+
class HelloHandler < Hooks::Plugins::Handlers::Base
225+
def call(payload:, headers:, config:)
226+
# Process the incoming webhook - optionally use the payload and headers
227+
# to perform some action or validation
228+
# For this example, we will just return a success message
229+
{
230+
message: "webhook processed successfully",
231+
handler: "HelloHandler",
232+
timestamp: Time.now.iso8601
233+
}
234+
end
235+
end
236+
```
237+
238+
And another handler plugin for the `/goodbye` endpoint:
239+
240+
```ruby
241+
# file: plugins/handlers/goodbye_handler.rb
242+
class GoodbyeHandler < Hooks::Plugins::Handlers::Base
243+
def call(payload:, headers:, config:)
244+
# Ditto for the goodbye endpoint
245+
{
246+
message: "goodbye webhook processed successfully",
247+
handler: "GoodbyeHandler",
248+
timestamp: Time.now.iso8601
249+
}
250+
end
251+
end
252+
```
253+
254+
#### 4. Implement authentication plugins (optional)
255+
256+
If you want to secure your webhook endpoints, you can create custom authentication plugins in the `plugins/auth` directory. Here is an example of a simple authentication plugin for the `/goodbye` endpoint:
257+
258+
```ruby
259+
# file: plugins/auth/goodbye.rb
260+
# this is a custom authentication plugin for the Goodbye endpoint
261+
# it is extremely simple and just checks if the Authorization header matches a secret for example purposes
262+
module Hooks
263+
module Plugins
264+
module Auth
265+
class Goodbye < Base
266+
def self.valid?(payload:, headers:, config:)
267+
# get the secret from environment variable as configured with secret_env_key
268+
secret = fetch_secret(config, secret_env_key_name: :secret_env_key)
269+
270+
# check if the Authorization header matches the secret
271+
auth_header = headers[config[:header]]
272+
return false unless auth_header
273+
274+
# compare the Authorization header with the secret
275+
Rack::Utils.secure_compare(auth_header, "Bearer #{secret}")
276+
end
277+
end
278+
end
279+
end
280+
end
281+
```
282+
283+
#### Summary
284+
285+
What these steps have done is set up a Hooks server that listens for incoming webhook requests at `/webhooks/hello` and `/webhooks/goodbye`. The `/hello` endpoint will respond with a success message without any authentication, while the `/goodbye` endpoint will require a valid `Authorization` header that matches the secret defined in the environment variable `GOODBYE_API_KEY`. Before the `/goodbye` endpoint enters the defined handler, it will first check the authentication plugin to ensure the request is valid.
286+
287+
To see a live working version of this example, check out the [spec/acceptance/](spec/acceptance/) directory in this repository, which is used for acceptance testing the Hooks framework. It contains a complete example of how to set up a Hooks server with custom plugins, authentication, and more.
288+
289+
### Authentication
290+
291+
See the [Auth Plugins](docs/auth_plugins.md) documentation for even more information on how to create your own custom authentication plugins.
292+
293+
## Contributing 🤝
294+
295+
See the [Contributing](CONTRIBUTING.md) document for information on how to contribute to the Hooks project, including setting up your development environment, running tests, and releasing new versions.

‎spec/acceptance/config/endpoints/with_custom_auth.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@ path: /with_custom_auth_plugin
22
handler: TestHandler
33

44
auth:
5-
type: example_auth_plugin
5+
type: example
66
secret_env_key: SHARED_SECRET # the name of the environment variable containing the shared secret
77
header: Authorization

spec/acceptance/plugins/auth/example_auth_plugin.rb renamed to spec/acceptance/plugins/auth/example.rb

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
module Hooks
88
module Plugins
99
module Auth
10-
class ExampleAuthPlugin < Base
10+
class Example < Base
1111
def self.valid?(payload:, headers:, config:)
1212
# Get the secret from environment variable as configured with secret_env_key
1313
secret = fetch_secret(config, secret_env_key_name: :secret_env_key)

0 commit comments

Comments
 (0)