Merge pull request #411 from OpenFn/webhook_auth

Webhook auth

Author: aleksa-krolls

docs/build/triggers.md

@@ -19,6 +19,10 @@ real-time event-based automation.
 
 ![Webhook Trigger](/img/webhook_trigger.png)
 
+To learn about how to add an additional layer of security to your Webhook
+Trigger by adding authentication, head over to our
+[Webhook Security](../manage-projects/webhook-auth.md) page.
+
 ### Cron Triggers (formerly timers)
 
 `Cron Triggers` run Workflows based on a cron schedule, and are good for

docs/manage-projects/webhook-auth.md

@@ -0,0 +1,75 @@
+---
+title: Webhook Security
+sidebar_label: Webhook Security
+slug: /webhook-security
+---
+
+This page guides you through the steps of adding an additional layer of security
+to your webhook.
+
+## Adding a Webhook Authentication Method
+
+In your OpenFn projects, you can utilize webhooks to receive data from external
+applications using a
+[Webhook Trigger](../build/triggers.md). When using a
+webhook, you can require external applications to authenticate before sending
+your project data for more security.
+
+OpenFn supports Basic HTTP Authentication using username and password, and API
+Key Authentication using the `x-api-key` request header.
+
+### Adding Authentication Via `Project Settings`
+
+You can add a new Authentication Method under `Webhook Security` of your
+`Project Settings`. The authentication you set up here can then be used in any
+of your Workflows within this Project.
+
+![Project Settings Webhook Security](/img/lightning_auth_project_settings.png)
+
+After clicking `New auth method`, choose the type - Basic HTTP or API Key
+Authentication.
+
+![New Auth Method](/img/lightning_choose_auth_method.png)
+
+#### Basic Auth
+
+For Basic Auth, give it a name, choose a username and password, and hit
+`Create Auth Method`.
+
+![Basic Auth](/img/lightning_basic_auth.png)
+
+#### API Key
+
+For API Key, just choose a name, and click `Create Auth Method`. An API key is
+generated for you.
+
+![API auth](/img/lightning_api_auth.png)
+
+You can edit or delete your auth methods on this page as well.
+
+// screenshot
+
+Once you added an auth method to a webhook, it will show up under
+`Linked Triggers`.
+
+![Linked Triggers](/img/lightning_linked_triggers.png)
+
+![Linked Triggers](/img/lightning_linked_triggers2.png)
+
+### Adding Authentication Via a Workflow
+
+On your Workflows you can use the auth methods you created under
+`Project Settings`, or you can create a new one.
+
+When you click on `Add authentication` under `Webhook Authentication`, select a
+(or multiple) existing method(s), or hit `Create a new webhook auth method`.
+Refer to the `Basic Auth` and `API Key` sections above for details on adding
+these.
+
+Once you've added an auth method, it will show up in your Webhook Trigger
+configuration.
+
+![Linked Triggers](/img/lightning_workflow_trigger_added.png)
+
+Only requests using these required auth details will be able to send data to
+your Workflow.

sidebars-main.js

@@ -104,6 +104,7 @@ module.exports = {
         'manage-projects/user-roles-permissions',
         'manage-projects/notifications',
         'manage-projects/link-to-gh',
+        'manage-projects/webhook-auth',
       ],
     },
     {