docs

Author: GrantBirki

docs/handler_plugins.md

@@ -2,6 +2,31 @@
 
 This document provides in-depth information about handler plugins and how you can create your own to extend the functionality of the Hooks framework for your own deployment.
 
+## Writing a Handler Plugin
+
+Handler plugins are Ruby classes that extend the `Hooks::Plugins::Handlers::Base` class. They are used to process webhook payloads and can do anything you want. They follow a very simple interface that allows you to define a `call` method that takes three parameters: `payload`, `headers`, and `config`. The `call` method should return a hash with the response data. The hash that this method returns will be sent back to the webhook sender as a JSON response.
+
+- `payload`: The webhook payload, which can be a Hash or a String. This is the data that the webhook sender sends to your endpoint.
+- `headers`: A Hash of HTTP headers that were sent with the webhook request.
+- `config`: A Hash containing the endpoint configuration. This can include any additional settings or parameters that you want to use in your handler. Most of the time, this won't be used but sometimes endpoint configs add `opts` that can be useful for the handler.
+
+```ruby
+# example file path: plugins/handlers/example.rb
+class Example < Hooks::Plugins::Handlers::Base
+  # Process a webhook payload
+  #
+  # @param payload [Hash, String] webhook payload
+  # @param headers [Hash<String, String>] HTTP headers
+  # @param config [Hash] Endpoint configuration
+  # @return [Hash] Response data
+  def call(payload:, headers:, config:)
+    return {
+      status: "success"
+    }
+  end
+end
+```
+
 ## Built-in Features
 
 This section goes into details on the built-in features that exist in all handler plugins that extend the `Hooks::Plugins::Handlers::Base` class.