From 1288cf323b4c4905a5d900124d40f5191c7a6f18 Mon Sep 17 00:00:00 2001 From: Alex Luong Date: Thu, 12 Oct 2023 23:00:53 +0700 Subject: [PATCH 1/8] docs: Add README and getting started docs --- README.md | 54 +++++ docs/guides/getting-started.md | 188 ++++++++++++++++++ docs/guides/register-external-webhooks.md | 148 ++++++++++++++ docs/guides/rules.md | 169 ++++++++++++++++ templates/guides/getting-started.md | 188 ++++++++++++++++++ .../guides/register-external-webhooks.md | 148 ++++++++++++++ templates/guides/rules.md | 169 ++++++++++++++++ 7 files changed, 1064 insertions(+) create mode 100644 docs/guides/getting-started.md create mode 100644 docs/guides/register-external-webhooks.md create mode 100644 docs/guides/rules.md create mode 100644 templates/guides/getting-started.md create mode 100644 templates/guides/register-external-webhooks.md create mode 100644 templates/guides/rules.md diff --git a/README.md b/README.md index 011642d..2ecf8cb 100644 --- a/README.md +++ b/README.md @@ -1 +1,55 @@ # Hookdeck Terraform Provider + +_[Hookdeck](https://hookdeck.com) is a prebuilt webhook infrastructure. It gives developers the tooling they need to monitor and troubleshoot all their inbound webhooks. For more information, see the [Ably documentation](https://ably.com/docs)._ + +This is a Terraform provider for Hookdeck that enables you to manage your Hookdeck account using IaC (Infrastructure-as-Code), including managing your sources, destinations, connections, transformations, and more. It also enables some webhook registration workflow that allows you to configure webhooks as part of your CI/CD processes. + +## Installation + +To install Hookdeck Terraform provider: + +1. Obtain your Hookdeck API key from [the dashboard](https://dashboard.hookdeck.com/workspace/secrets) +2. Add the following to your Terraform configuration file + +```hcl +terraform { + required_providers { + ably = { + source = "ably/ably" + version = "0.1.2" + } + } +} + +provider "hookdeck" { + # set HOOKDECK_API_KEY env var or optionally specify the key in the provider configuration + api_key = var.hookdeck_api_key +} +``` + +## Using the provider + +This readme gives a basic example; for more examples see the [examples/](examples/) folder, rendered documentation on the [Terraform Registry](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs), or [docs folder](docs/) in this repository. + +```hcl +# Configure a source +resource "hookdeck_source" "my_source" { + name = "my_source" +} + +# Configure a destination +resource "hookdeck_destination" "my_destination" { + name = "my_destination" + url = "https://mock.hookdeck.com" +} + +# Configure a connection +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id +} +``` + +## Dependencies + +This provider uses [Hookdeck API](https://hookdeck.com/api-ref) and [Hookdeck Go SDK](https://github.com/hookdeck/hookdeck-go-sdk) under the hood. diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md new file mode 100644 index 0000000..e2d3d71 --- /dev/null +++ b/docs/guides/getting-started.md @@ -0,0 +1,188 @@ +--- +page_title: "Getting Started" +description: "Getting Started with Hookdeck Provider" +--- + +# Getting Started with Hookdeck Provider + +## Hookdeck + +Hookdeck is a prebuilt webhook infrastructure. It gives developers the tooling they need to monitor and troubleshoot all their inbound webhooks. + +Once integrated, Hookdeck unlocks an entire suite of tools: [alerting](https://hookdeck.com/docs/notifications), [rate limiting](https://hookdeck.com/docs/set-a-rate-limit), [automatic retries](https://hookdeck.com/docs/automatically-retry-events), [one-to-many delivery](https://hookdeck.com/docs/create-a-destination), [payload transformations](https://hookdeck.com/docs/transformations), local testing via the [CLI](https://hookdeck.com/docs/using-the-cli), a feature-rich [API](https://hookdeck.com/docs/using-the-api), and more. It acts as a proxy – routing webhooks from any [source](https://hookdeck.com/docs/sources) to a specified [destination](destinations) – so you can spend less time maintaining an asynchronous event infrastructure and more time building the features your users care about. + +-> Visit the [Documentation](https://hookdeck.com/docs/introduction) to learn more about Hookdeck. + +## Terraform + +[Terraform](https://developer.hashicorp.com/terraform/intro) is an open-source Infrastructure as Code (IaC) tool that allows you to define and manage infrastructure resources using HashiCorp Configuration Language (HCL). It can be used to manage a wide range of resources, including servers, storage, networks, and cloud services. Terraform is a popular choice for infrastructure automation because it is easy to use, flexible, and powerful. + +Hookdeck provides a Terraform provider that helps you utilize Terraform to configure your workspace declaratively instead of relying on the dashboard. You can run Terraform in your CI/CD pipeline and maintain Hookdeck workspace configuration programmatically as part of your deployment workflow. + +To get started, follow its documentation to [install Terraform CLI locally](https://developer.hashicorp.com/terraform/downloads). + +## Tutorial + +Before you begin, make sure you have Terraform CLI installed locally and a Hookdeck API Key obtained from [the dashboard](https://dashboard/hookdeck.com/workspace/secrets). + +### Initialize Terraform + +In a directory of your choice, create a Terraform config file `main.tf`. + +```hcl +# main.tf + +terraform { + required_providers { + hookdeck = { + source = "hookdeck/hookdeck" + version = "~> 0.1" + } + } +} + +provider "hookdeck" { + api_key = "" +} +``` + +-> Replace `` with your Hookdeck workspace API key. + +After creating your basic configuration in HCL, initialize Terraform and ask it to apply the configuration to Cloudflare. + +```sh +$ terraform init +``` + +Running `terraform init` will download every required plugins in the configuration file, such as Hookdeck Terraform provider, to a local `.terraform`` directory. + +Afterwards, you can run `terraform plan` to confirm that you have Terraform properly installed. As you haven't added any resource to for Terraform to manage yet, it will indicate that there are no changes planned with the current state of your infrastructure. + +``` +$ terraform plan +``` + +### Source + +First, let's create a source resource with Terraform. You can add this resource block to the end of your Terraform configuration file + +```hcl +resource "hookdeck_source" "my_source" { + name = "my_source" +} +``` + +Now, try `terraform plan` again to see what Terraform may suggest + +```sh +$ terraform plan +``` + +``` +Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: + + create + +Terraform will perform the following actions: + + # hookdeck_source.my_source will be created + + resource "hookdeck_source" "my_source" { + + allowed_http_methods = [ + + "POST", + + "PUT", + + "PATCH", + + "DELETE", + ] + + archived_at = (known after apply) + + created_at = (known after apply) + + id = (known after apply) + + name = "my_source" + + team_id = (known after apply) + + updated_at = (known after apply) + + url = (known after apply) + } + +Plan: 1 to add, 0 to change, 0 to destroy. + +───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── + +Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now. +``` + +You can execute this change and create a source in your workspace like so. + +```sh +$ terraform apply +``` + +You can check the dashboard to confirm that a new source was created in your workspace. + +To learn more about what options you have with Hookdeck's Source on Terraform, check out [its documentation here](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/source). + +### Destination + +Here's what a simple destination resource should look with Terraform + +```hcl +resource "hookdeck_destination" "my_destination" { + name = "my_destination" + url = "https://mock.hookdeck.com" +} +``` + +This is a Mock destination which will accepts all of your events so you can inspect on Hookdeck's dashboard. + +Similarly, you can run `terraform apply` to create your new destination. As you should see, when running `terraform apply`, Terraform will show the plan and ask for your confirmation before executing it, so you don't need to run `terraform plan` beforehand. + +To learn more about what options you have with Hookdeck's Destination on Terraform, check out [its documentation here](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/destination). + +### Connection + +Lastly, you can create a Hookdeck connection to connect your newly created source and destination. + +```hcl +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id +} +``` + +To learn more about what options you have with Hookdeck's Connection on Terraform, check out [its documentation here](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/connection). + +### Summary + +In this tutorial, you have + +- installed Terraform CLI locally and initialized a Terraform project with Hookdeck provider with `terraform init` +- written the configuration code for a Hookdeck source, destination, and connection using Terraform's own declarative programming language HCL +- reviewed and executed the Terraform plan with `terraform plan` and `terraform apply` + +Here's the final `main.tf` file: + +``` +terraform { + required_providers { + hookdeck = { + source = "hookdeck/hookdeck" + version = "~> 0.1" + } + } +} + +provider "hookdeck" { + api_key = "" +} + +resource "hookdeck_source" "my_source" { + name = "my_source" +} + +resource "hookdeck_destination" "my_destination" { + name = "my_destination" + url = "https://mock.hookdeck.com" +} + +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id +} +``` diff --git a/docs/guides/register-external-webhooks.md b/docs/guides/register-external-webhooks.md new file mode 100644 index 0000000..e7f4b3b --- /dev/null +++ b/docs/guides/register-external-webhooks.md @@ -0,0 +1,148 @@ +--- +page_title: "Register External Webhooks" +description: "Register External Webhooks with Hookdeck Provider" +--- + +# Register External Webhooks + +Hookdeck Terraform provider provides a solution to help register and unregister webhooks with your providers. It's provider-agnostic, so as long as there's an endpoint to manage webhooks programmatically, you should be able to configure it as part of your workflow. + +## Setup + +For example, let's say you're using Stripe for payment and want to listen to `charge.succeeded` and `charge.failed` webhook events. Let's start with connection to start listening to incoming webhooks from Stripe. + +```hcl +resource "hookdeck_source" "stripe" { + name = "stripe" +} + +resource "hookdeck_destination" "payment_service" { + name = "my_destination" + url = "https://api.my-app.com/webhooks/stripe" +} + +resource "hookdeck_connection" "stripe_payment_service" { + source_id = hookdeck_source.stripe.id + destination_id = hookdeck_destination.payment_service.id +} +``` + +## Register Stripe webhook + +Stripe provides API endpoints to [create a new webhook](https://stripe.com/docs/api/webhook_endpoints/create) and [delete existing webhook](https://stripe.com/docs/api/webhook_endpoints/delete) which we will use in this example. + +```hcl +resource "webhook_registration" "stripe" { + provider = hookdeck + + register = { + request = { + method = "POST" + url = "https://api.stripe.com/v1/webhook_endpoints" + headers = jsonencode({ + "content-type" = "application/json" + authorization = "Bearer " + }) + body = jsonencode({ + url = hookdeck_source.stripe.url + enabled_events = [ + "charge.failed", + "charge.succeeded" + ] + }) + } + } + unregister = { + request = { + method = "DELETE" + url = "https://api.stripe.com/v1/webhook_endpoints/{{.register.response.body.id}}" + headers = jsonencode({ + authorization = "Bearer " + }) + } + } +} +``` + +For many API, you will need the ID of the registered webhook to unregister. You can usually get the ID of the newly registered webhook from the register API response itself. Because of that, Hookdeck Terraform provider will save that response for use in the `unregister` flow. The string values when you configure your `unregister` property are string templates where you'll have access to `.register.response` data which is the HTTP response from the original registration API request. + +## Use webhook secret to verify with Hookdeck + +Another way you can use the `webhook_registration` resource is to configure Hookdeck [source verification](https://hookdeck.com/docs/signature-verification) as part of your Terraform workflow. With the `webhook_registration` resource above, you can now configure Hookdeck verification like so: + +```hcl +resource "hookdeck_source_verification" "stripe_verification" { + source_id = hookdeck_source.stripe.id + verification = { + stripe = { + webhook_secret_key = jsondecode(webhook_registration.stripe.register.response).body.secret + } + } +} +``` + +As mentioned in the section earlier, the provider will save the response from the registration request to be used later (unregister flow). For some API, that response will also contain some secret information that you can use for verification purposes. As the `webhook_registration` is provider-agnostic, it saves the response in a strigified JSON with 2 fields "body" and "headers". When using that data in the unregistration flow, the provider constructs that response and use it in the template for you to use. When using it in other resources, you will need to decode the stringified JSON using [`jsondecode`](https://developer.hashicorp.com/terraform/language/functions/jsondecode) like the example above. + +Putting everything together, to register Stripe webhook with Hookdeck source with source verification, here's how your Terraform code would look like: + +```hcl +# Configure Hookdeck source, destination, and connection + +resource "hookdeck_source" "stripe" { + name = "stripe" +} + +resource "hookdeck_destination" "payment_service" { + name = "my_destination" + url = "https://api.my-app.com/webhooks/stripe" +} + +resource "hookdeck_connection" "stripe_payment_service" { + source_id = hookdeck_source.stripe.id + destination_id = hookdeck_destination.payment_service.id +} + +# Register Stripe webhook + +resource "webhook_registration" "stripe" { + provider = hookdeck + + register = { + request = { + method = "POST" + url = "https://api.stripe.com/v1/webhook_endpoints" + headers = jsonencode({ + "content-type" = "application/json" + authorization = "Bearer " + }) + body = jsonencode({ + url = hookdeck_source.stripe.url + enabled_events = [ + "charge.failed", + "charge.succeeded" + ] + }) + } + } + unregister = { + request = { + method = "DELETE" + url = "https://api.stripe.com/v1/webhook_endpoints/{{.register.response.body.id}}" + headers = jsonencode({ + authorization = "Bearer " + }) + } + } +} + +# Configure source verification + +resource "hookdeck_source_verification" "stripe_verification" { + source_id = hookdeck_source.stripe.id + verification = { + stripe = { + webhook_secret_key = jsondecode(webhook_registration.stripe.register.response).body.secret + } + } +} +``` diff --git a/docs/guides/rules.md b/docs/guides/rules.md new file mode 100644 index 0000000..1dba951 --- /dev/null +++ b/docs/guides/rules.md @@ -0,0 +1,169 @@ +--- +page_title: "Connection Rules" +description: "Connection Rules" +--- + +# Hookdeck Rules + +A rule is a piece of instructional logic that dictates the behavior of events routed through a connection. There are 4 types of rules in Hookdeck: + +## Retry rule + +The retry rule determines the rate and limit of [automatic retries](automatically-retry-events) on failed events. + +| Retry Rule Element | Explanation | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Strategy | A **linear** strategy means retries will occur at regular intervals; an **exponential** strategy means each retry will be delayed twice as long as the previous (1 hour, 2 hours, 4 hours...) | +| Interval | The delay between each automatic retry | +| Count | The number of automatic retries Hookdeck will attempt after an event fails | + +> Automatic retries max out after one week, or {% $MAX_AUTOMATIC_RETRY_ATTEMPTS %} attempts – whichever comes first. Events can be [manually retried](manually-retry-events) after exceeding this limit. + +Here's how a connection with a linear retry strategy with 5 attempts per hour should look like: + +```hcl +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id + rules = [ + { + retry_rule = { + count = 5 + interval = 3600000 + strategy = "linear" + } + } + ] +} +``` + +## Delay rule + +The delay rule allows you to introduce a delay between the moment Hookdeck receives an event, and when it's forwarded to your destination. + +Here's how a connection with a 10-second delay rule look like: + +```hcl +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id + rules = [ + { + delay_rule = { + delay = 10000 + } + } + ] +} +``` + +## Filter rule + +The filter rule allows you to route webhooks differently based on the contents of their `Headers`, `Body`, `Query`, and/or `Path`. + +For more information on how to set up filters, see our [filter documentation](https://hookdeck.com/docs/filters). + +Here's how a connection with a filter look like: + +```hcl +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id + rules = [ + { + filter_rule = { + body = { + json = "{\"hello\":\"world\"}" + } + path = { + string = "/api/webhook" + } + query = { + boolean = false + } + headers = { + number = 10 + } + } + } + ] +} +``` + +As the Terraform provider expects a stringified JSON value for the JSON rule, there are some other approaches that you can use to configure your connection to your liking: + +- Using Terraform's [`jsonencoded`](https://developer.hashicorp.com/terraform/language/functions/jsonencode) for better readbility inline: + +```hcl +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id + rules = [ + { + filter_rule = { + body = { + json = jsonencode({ + hello = "world" + }) + } + } + } + ] +} +``` + +- Using Terraform's [`file`](https://developer.hashicorp.com/terraform/language/functions/file) to write your filter code in a separate file: + +```hcl +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id + rules = [ + { + filter_rule = { + body = { + json = file("${path.module}/filters/my_connection_body.json") + } + } + } + ] +} +``` + +## Transformation rule + +The transformation rule allows you to modify the payload of a webhook before it gets delivered to a destination. + +For more information on how to set up transformations, see our [transformation documentation](https://hookdeck.com/docs/transformations). + +To use transformation with Terraform, you need to create a new transformation before using it with your connection. Here's how that should look: + +```hcl +resource "hookdeck_transformation" "my_transformation" { + name = "my_transformation" + code = "addHandler('transform', (request, context) => request);" +} + +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id + rules = [ + { + transform_rule = { + transformation_id = hookdeck_transformation.my_transformation.id + } + } + ] +} +``` + +As the transformation code also expects a stringified function handler, you can also keep your transformation code in a separate file. + +```hcl +resource "hookdeck_transformation" "my_transformation" { + name = "my_transformation" + code = file("${path.module}/transformations/my_transformation.js") +} +``` + +-> With Hookdeck Terraform provider, you can keep your filter and transformation code in version control. diff --git a/templates/guides/getting-started.md b/templates/guides/getting-started.md new file mode 100644 index 0000000..e2d3d71 --- /dev/null +++ b/templates/guides/getting-started.md @@ -0,0 +1,188 @@ +--- +page_title: "Getting Started" +description: "Getting Started with Hookdeck Provider" +--- + +# Getting Started with Hookdeck Provider + +## Hookdeck + +Hookdeck is a prebuilt webhook infrastructure. It gives developers the tooling they need to monitor and troubleshoot all their inbound webhooks. + +Once integrated, Hookdeck unlocks an entire suite of tools: [alerting](https://hookdeck.com/docs/notifications), [rate limiting](https://hookdeck.com/docs/set-a-rate-limit), [automatic retries](https://hookdeck.com/docs/automatically-retry-events), [one-to-many delivery](https://hookdeck.com/docs/create-a-destination), [payload transformations](https://hookdeck.com/docs/transformations), local testing via the [CLI](https://hookdeck.com/docs/using-the-cli), a feature-rich [API](https://hookdeck.com/docs/using-the-api), and more. It acts as a proxy – routing webhooks from any [source](https://hookdeck.com/docs/sources) to a specified [destination](destinations) – so you can spend less time maintaining an asynchronous event infrastructure and more time building the features your users care about. + +-> Visit the [Documentation](https://hookdeck.com/docs/introduction) to learn more about Hookdeck. + +## Terraform + +[Terraform](https://developer.hashicorp.com/terraform/intro) is an open-source Infrastructure as Code (IaC) tool that allows you to define and manage infrastructure resources using HashiCorp Configuration Language (HCL). It can be used to manage a wide range of resources, including servers, storage, networks, and cloud services. Terraform is a popular choice for infrastructure automation because it is easy to use, flexible, and powerful. + +Hookdeck provides a Terraform provider that helps you utilize Terraform to configure your workspace declaratively instead of relying on the dashboard. You can run Terraform in your CI/CD pipeline and maintain Hookdeck workspace configuration programmatically as part of your deployment workflow. + +To get started, follow its documentation to [install Terraform CLI locally](https://developer.hashicorp.com/terraform/downloads). + +## Tutorial + +Before you begin, make sure you have Terraform CLI installed locally and a Hookdeck API Key obtained from [the dashboard](https://dashboard/hookdeck.com/workspace/secrets). + +### Initialize Terraform + +In a directory of your choice, create a Terraform config file `main.tf`. + +```hcl +# main.tf + +terraform { + required_providers { + hookdeck = { + source = "hookdeck/hookdeck" + version = "~> 0.1" + } + } +} + +provider "hookdeck" { + api_key = "" +} +``` + +-> Replace `` with your Hookdeck workspace API key. + +After creating your basic configuration in HCL, initialize Terraform and ask it to apply the configuration to Cloudflare. + +```sh +$ terraform init +``` + +Running `terraform init` will download every required plugins in the configuration file, such as Hookdeck Terraform provider, to a local `.terraform`` directory. + +Afterwards, you can run `terraform plan` to confirm that you have Terraform properly installed. As you haven't added any resource to for Terraform to manage yet, it will indicate that there are no changes planned with the current state of your infrastructure. + +``` +$ terraform plan +``` + +### Source + +First, let's create a source resource with Terraform. You can add this resource block to the end of your Terraform configuration file + +```hcl +resource "hookdeck_source" "my_source" { + name = "my_source" +} +``` + +Now, try `terraform plan` again to see what Terraform may suggest + +```sh +$ terraform plan +``` + +``` +Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: + + create + +Terraform will perform the following actions: + + # hookdeck_source.my_source will be created + + resource "hookdeck_source" "my_source" { + + allowed_http_methods = [ + + "POST", + + "PUT", + + "PATCH", + + "DELETE", + ] + + archived_at = (known after apply) + + created_at = (known after apply) + + id = (known after apply) + + name = "my_source" + + team_id = (known after apply) + + updated_at = (known after apply) + + url = (known after apply) + } + +Plan: 1 to add, 0 to change, 0 to destroy. + +───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── + +Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now. +``` + +You can execute this change and create a source in your workspace like so. + +```sh +$ terraform apply +``` + +You can check the dashboard to confirm that a new source was created in your workspace. + +To learn more about what options you have with Hookdeck's Source on Terraform, check out [its documentation here](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/source). + +### Destination + +Here's what a simple destination resource should look with Terraform + +```hcl +resource "hookdeck_destination" "my_destination" { + name = "my_destination" + url = "https://mock.hookdeck.com" +} +``` + +This is a Mock destination which will accepts all of your events so you can inspect on Hookdeck's dashboard. + +Similarly, you can run `terraform apply` to create your new destination. As you should see, when running `terraform apply`, Terraform will show the plan and ask for your confirmation before executing it, so you don't need to run `terraform plan` beforehand. + +To learn more about what options you have with Hookdeck's Destination on Terraform, check out [its documentation here](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/destination). + +### Connection + +Lastly, you can create a Hookdeck connection to connect your newly created source and destination. + +```hcl +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id +} +``` + +To learn more about what options you have with Hookdeck's Connection on Terraform, check out [its documentation here](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/connection). + +### Summary + +In this tutorial, you have + +- installed Terraform CLI locally and initialized a Terraform project with Hookdeck provider with `terraform init` +- written the configuration code for a Hookdeck source, destination, and connection using Terraform's own declarative programming language HCL +- reviewed and executed the Terraform plan with `terraform plan` and `terraform apply` + +Here's the final `main.tf` file: + +``` +terraform { + required_providers { + hookdeck = { + source = "hookdeck/hookdeck" + version = "~> 0.1" + } + } +} + +provider "hookdeck" { + api_key = "" +} + +resource "hookdeck_source" "my_source" { + name = "my_source" +} + +resource "hookdeck_destination" "my_destination" { + name = "my_destination" + url = "https://mock.hookdeck.com" +} + +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id +} +``` diff --git a/templates/guides/register-external-webhooks.md b/templates/guides/register-external-webhooks.md new file mode 100644 index 0000000..e7f4b3b --- /dev/null +++ b/templates/guides/register-external-webhooks.md @@ -0,0 +1,148 @@ +--- +page_title: "Register External Webhooks" +description: "Register External Webhooks with Hookdeck Provider" +--- + +# Register External Webhooks + +Hookdeck Terraform provider provides a solution to help register and unregister webhooks with your providers. It's provider-agnostic, so as long as there's an endpoint to manage webhooks programmatically, you should be able to configure it as part of your workflow. + +## Setup + +For example, let's say you're using Stripe for payment and want to listen to `charge.succeeded` and `charge.failed` webhook events. Let's start with connection to start listening to incoming webhooks from Stripe. + +```hcl +resource "hookdeck_source" "stripe" { + name = "stripe" +} + +resource "hookdeck_destination" "payment_service" { + name = "my_destination" + url = "https://api.my-app.com/webhooks/stripe" +} + +resource "hookdeck_connection" "stripe_payment_service" { + source_id = hookdeck_source.stripe.id + destination_id = hookdeck_destination.payment_service.id +} +``` + +## Register Stripe webhook + +Stripe provides API endpoints to [create a new webhook](https://stripe.com/docs/api/webhook_endpoints/create) and [delete existing webhook](https://stripe.com/docs/api/webhook_endpoints/delete) which we will use in this example. + +```hcl +resource "webhook_registration" "stripe" { + provider = hookdeck + + register = { + request = { + method = "POST" + url = "https://api.stripe.com/v1/webhook_endpoints" + headers = jsonencode({ + "content-type" = "application/json" + authorization = "Bearer " + }) + body = jsonencode({ + url = hookdeck_source.stripe.url + enabled_events = [ + "charge.failed", + "charge.succeeded" + ] + }) + } + } + unregister = { + request = { + method = "DELETE" + url = "https://api.stripe.com/v1/webhook_endpoints/{{.register.response.body.id}}" + headers = jsonencode({ + authorization = "Bearer " + }) + } + } +} +``` + +For many API, you will need the ID of the registered webhook to unregister. You can usually get the ID of the newly registered webhook from the register API response itself. Because of that, Hookdeck Terraform provider will save that response for use in the `unregister` flow. The string values when you configure your `unregister` property are string templates where you'll have access to `.register.response` data which is the HTTP response from the original registration API request. + +## Use webhook secret to verify with Hookdeck + +Another way you can use the `webhook_registration` resource is to configure Hookdeck [source verification](https://hookdeck.com/docs/signature-verification) as part of your Terraform workflow. With the `webhook_registration` resource above, you can now configure Hookdeck verification like so: + +```hcl +resource "hookdeck_source_verification" "stripe_verification" { + source_id = hookdeck_source.stripe.id + verification = { + stripe = { + webhook_secret_key = jsondecode(webhook_registration.stripe.register.response).body.secret + } + } +} +``` + +As mentioned in the section earlier, the provider will save the response from the registration request to be used later (unregister flow). For some API, that response will also contain some secret information that you can use for verification purposes. As the `webhook_registration` is provider-agnostic, it saves the response in a strigified JSON with 2 fields "body" and "headers". When using that data in the unregistration flow, the provider constructs that response and use it in the template for you to use. When using it in other resources, you will need to decode the stringified JSON using [`jsondecode`](https://developer.hashicorp.com/terraform/language/functions/jsondecode) like the example above. + +Putting everything together, to register Stripe webhook with Hookdeck source with source verification, here's how your Terraform code would look like: + +```hcl +# Configure Hookdeck source, destination, and connection + +resource "hookdeck_source" "stripe" { + name = "stripe" +} + +resource "hookdeck_destination" "payment_service" { + name = "my_destination" + url = "https://api.my-app.com/webhooks/stripe" +} + +resource "hookdeck_connection" "stripe_payment_service" { + source_id = hookdeck_source.stripe.id + destination_id = hookdeck_destination.payment_service.id +} + +# Register Stripe webhook + +resource "webhook_registration" "stripe" { + provider = hookdeck + + register = { + request = { + method = "POST" + url = "https://api.stripe.com/v1/webhook_endpoints" + headers = jsonencode({ + "content-type" = "application/json" + authorization = "Bearer " + }) + body = jsonencode({ + url = hookdeck_source.stripe.url + enabled_events = [ + "charge.failed", + "charge.succeeded" + ] + }) + } + } + unregister = { + request = { + method = "DELETE" + url = "https://api.stripe.com/v1/webhook_endpoints/{{.register.response.body.id}}" + headers = jsonencode({ + authorization = "Bearer " + }) + } + } +} + +# Configure source verification + +resource "hookdeck_source_verification" "stripe_verification" { + source_id = hookdeck_source.stripe.id + verification = { + stripe = { + webhook_secret_key = jsondecode(webhook_registration.stripe.register.response).body.secret + } + } +} +``` diff --git a/templates/guides/rules.md b/templates/guides/rules.md new file mode 100644 index 0000000..1dba951 --- /dev/null +++ b/templates/guides/rules.md @@ -0,0 +1,169 @@ +--- +page_title: "Connection Rules" +description: "Connection Rules" +--- + +# Hookdeck Rules + +A rule is a piece of instructional logic that dictates the behavior of events routed through a connection. There are 4 types of rules in Hookdeck: + +## Retry rule + +The retry rule determines the rate and limit of [automatic retries](automatically-retry-events) on failed events. + +| Retry Rule Element | Explanation | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Strategy | A **linear** strategy means retries will occur at regular intervals; an **exponential** strategy means each retry will be delayed twice as long as the previous (1 hour, 2 hours, 4 hours...) | +| Interval | The delay between each automatic retry | +| Count | The number of automatic retries Hookdeck will attempt after an event fails | + +> Automatic retries max out after one week, or {% $MAX_AUTOMATIC_RETRY_ATTEMPTS %} attempts – whichever comes first. Events can be [manually retried](manually-retry-events) after exceeding this limit. + +Here's how a connection with a linear retry strategy with 5 attempts per hour should look like: + +```hcl +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id + rules = [ + { + retry_rule = { + count = 5 + interval = 3600000 + strategy = "linear" + } + } + ] +} +``` + +## Delay rule + +The delay rule allows you to introduce a delay between the moment Hookdeck receives an event, and when it's forwarded to your destination. + +Here's how a connection with a 10-second delay rule look like: + +```hcl +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id + rules = [ + { + delay_rule = { + delay = 10000 + } + } + ] +} +``` + +## Filter rule + +The filter rule allows you to route webhooks differently based on the contents of their `Headers`, `Body`, `Query`, and/or `Path`. + +For more information on how to set up filters, see our [filter documentation](https://hookdeck.com/docs/filters). + +Here's how a connection with a filter look like: + +```hcl +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id + rules = [ + { + filter_rule = { + body = { + json = "{\"hello\":\"world\"}" + } + path = { + string = "/api/webhook" + } + query = { + boolean = false + } + headers = { + number = 10 + } + } + } + ] +} +``` + +As the Terraform provider expects a stringified JSON value for the JSON rule, there are some other approaches that you can use to configure your connection to your liking: + +- Using Terraform's [`jsonencoded`](https://developer.hashicorp.com/terraform/language/functions/jsonencode) for better readbility inline: + +```hcl +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id + rules = [ + { + filter_rule = { + body = { + json = jsonencode({ + hello = "world" + }) + } + } + } + ] +} +``` + +- Using Terraform's [`file`](https://developer.hashicorp.com/terraform/language/functions/file) to write your filter code in a separate file: + +```hcl +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id + rules = [ + { + filter_rule = { + body = { + json = file("${path.module}/filters/my_connection_body.json") + } + } + } + ] +} +``` + +## Transformation rule + +The transformation rule allows you to modify the payload of a webhook before it gets delivered to a destination. + +For more information on how to set up transformations, see our [transformation documentation](https://hookdeck.com/docs/transformations). + +To use transformation with Terraform, you need to create a new transformation before using it with your connection. Here's how that should look: + +```hcl +resource "hookdeck_transformation" "my_transformation" { + name = "my_transformation" + code = "addHandler('transform', (request, context) => request);" +} + +resource "hookdeck_connection" "my_connection" { + source_id = hookdeck_source.my_source.id + destination_id = hookdeck_destination.my_destination.id + rules = [ + { + transform_rule = { + transformation_id = hookdeck_transformation.my_transformation.id + } + } + ] +} +``` + +As the transformation code also expects a stringified function handler, you can also keep your transformation code in a separate file. + +```hcl +resource "hookdeck_transformation" "my_transformation" { + name = "my_transformation" + code = file("${path.module}/transformations/my_transformation.js") +} +``` + +-> With Hookdeck Terraform provider, you can keep your filter and transformation code in version control. From 27341e3b55ffe7260019d857d64118acff63e4bf Mon Sep 17 00:00:00 2001 From: Alex Luong Date: Fri, 13 Oct 2023 01:22:00 +0700 Subject: [PATCH 2/8] fix: Replace Ably references --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2ecf8cb..fb5cd4e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Hookdeck Terraform Provider -_[Hookdeck](https://hookdeck.com) is a prebuilt webhook infrastructure. It gives developers the tooling they need to monitor and troubleshoot all their inbound webhooks. For more information, see the [Ably documentation](https://ably.com/docs)._ +_[Hookdeck](https://hookdeck.com) is a prebuilt webhook infrastructure. It gives developers the tooling they need to monitor and troubleshoot all their inbound webhooks. For more information, see the [Hookdeck documentation](https://hookdeck.com/docs)._ This is a Terraform provider for Hookdeck that enables you to manage your Hookdeck account using IaC (Infrastructure-as-Code), including managing your sources, destinations, connections, transformations, and more. It also enables some webhook registration workflow that allows you to configure webhooks as part of your CI/CD processes. @@ -14,8 +14,8 @@ To install Hookdeck Terraform provider: ```hcl terraform { required_providers { - ably = { - source = "ably/ably" + hookdeck = { + source = "hookdeck/hookdeck" version = "0.1.2" } } From 3492ce1477aa8d9d2f13338561501ea47d80b38e Mon Sep 17 00:00:00 2001 From: Phil Leggetter Date: Mon, 23 Oct 2023 21:53:44 +0100 Subject: [PATCH 3/8] chore: docs review updates --- README.md | 8 ++-- docs/guides/getting-started.md | 2 +- templates/guides/getting-started.md | 44 ++++++++++--------- .../guides/register-external-webhooks.md | 14 +++--- templates/guides/rules.md | 16 +++---- 5 files changed, 44 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index fb5cd4e..eb51067 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,15 @@ # Hookdeck Terraform Provider -_[Hookdeck](https://hookdeck.com) is a prebuilt webhook infrastructure. It gives developers the tooling they need to monitor and troubleshoot all their inbound webhooks. For more information, see the [Hookdeck documentation](https://hookdeck.com/docs)._ +_The [Hookdeck Event Gateway](https://hookdeck.com) enables engineering teams to build, deploy, observe, and scale event-driven applications. For more information, see the [Hookdeck documentation](https://hookdeck.com/docs)._ -This is a Terraform provider for Hookdeck that enables you to manage your Hookdeck account using IaC (Infrastructure-as-Code), including managing your sources, destinations, connections, transformations, and more. It also enables some webhook registration workflow that allows you to configure webhooks as part of your CI/CD processes. +The Hookdeck Terraform provider enables you to manage your Hookdeck workspaces using IaC (Infrastructure-as-Code), including managing your sources, destinations, connections, transformations, and more. It also supports webhook registration workflow that allows you to configure webhooks as part of your CI/CD processes. ## Installation To install Hookdeck Terraform provider: 1. Obtain your Hookdeck API key from [the dashboard](https://dashboard.hookdeck.com/workspace/secrets) -2. Add the following to your Terraform configuration file +2. Add the following to your Terraform configuration file: ```hcl terraform { @@ -29,7 +29,7 @@ provider "hookdeck" { ## Using the provider -This readme gives a basic example; for more examples see the [examples/](examples/) folder, rendered documentation on the [Terraform Registry](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs), or [docs folder](docs/) in this repository. +This README gives a basic example; for more examples, see the [examples/](examples/) folder, the rendered documentation on the [Terraform Registry](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs), or [docs folder](docs/) in this repository. ```hcl # Configure a source diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index e2d3d71..770ef41 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -11,7 +11,7 @@ Hookdeck is a prebuilt webhook infrastructure. It gives developers the tooling t Once integrated, Hookdeck unlocks an entire suite of tools: [alerting](https://hookdeck.com/docs/notifications), [rate limiting](https://hookdeck.com/docs/set-a-rate-limit), [automatic retries](https://hookdeck.com/docs/automatically-retry-events), [one-to-many delivery](https://hookdeck.com/docs/create-a-destination), [payload transformations](https://hookdeck.com/docs/transformations), local testing via the [CLI](https://hookdeck.com/docs/using-the-cli), a feature-rich [API](https://hookdeck.com/docs/using-the-api), and more. It acts as a proxy – routing webhooks from any [source](https://hookdeck.com/docs/sources) to a specified [destination](destinations) – so you can spend less time maintaining an asynchronous event infrastructure and more time building the features your users care about. --> Visit the [Documentation](https://hookdeck.com/docs/introduction) to learn more about Hookdeck. +Visit the [Hookdeck documentation](https://hookdeck.com/docs/introduction) to learn more. ## Terraform diff --git a/templates/guides/getting-started.md b/templates/guides/getting-started.md index e2d3d71..f8355bb 100644 --- a/templates/guides/getting-started.md +++ b/templates/guides/getting-started.md @@ -7,27 +7,27 @@ description: "Getting Started with Hookdeck Provider" ## Hookdeck -Hookdeck is a prebuilt webhook infrastructure. It gives developers the tooling they need to monitor and troubleshoot all their inbound webhooks. +The Hookdeck Event Gateway enables engineering teams to build, deploy, observe, and scale event-driven applications. -Once integrated, Hookdeck unlocks an entire suite of tools: [alerting](https://hookdeck.com/docs/notifications), [rate limiting](https://hookdeck.com/docs/set-a-rate-limit), [automatic retries](https://hookdeck.com/docs/automatically-retry-events), [one-to-many delivery](https://hookdeck.com/docs/create-a-destination), [payload transformations](https://hookdeck.com/docs/transformations), local testing via the [CLI](https://hookdeck.com/docs/using-the-cli), a feature-rich [API](https://hookdeck.com/docs/using-the-api), and more. It acts as a proxy – routing webhooks from any [source](https://hookdeck.com/docs/sources) to a specified [destination](destinations) – so you can spend less time maintaining an asynchronous event infrastructure and more time building the features your users care about. +Once integrated, Hookdeck unlocks an entire suite of tools: [alerting](https://hookdeck.com/docs/notifications), [rate limiting](https://hookdeck.com/docs/set-a-rate-limit), [automatic retries](https://hookdeck.com/docs/automatically-retry-events), [one-to-many delivery](https://hookdeck.com/docs/create-a-destination), [payload transformations](https://hookdeck.com/docs/transformations), local testing via the [CLI](https://hookdeck.com/docs/using-the-cli), a feature-rich [API](https://hookdeck.com/docs/using-the-api), and more. It acts as a proxy – routing webhooks from any [source](https://hookdeck.com/docs/sources) to a specified [destination](destinations). --> Visit the [Documentation](https://hookdeck.com/docs/introduction) to learn more about Hookdeck. +Visit the [Hookdeck documentation](https://hookdeck.com/docs/introduction) to learn more. ## Terraform [Terraform](https://developer.hashicorp.com/terraform/intro) is an open-source Infrastructure as Code (IaC) tool that allows you to define and manage infrastructure resources using HashiCorp Configuration Language (HCL). It can be used to manage a wide range of resources, including servers, storage, networks, and cloud services. Terraform is a popular choice for infrastructure automation because it is easy to use, flexible, and powerful. -Hookdeck provides a Terraform provider that helps you utilize Terraform to configure your workspace declaratively instead of relying on the dashboard. You can run Terraform in your CI/CD pipeline and maintain Hookdeck workspace configuration programmatically as part of your deployment workflow. +The Hookdeck Terraform provider helps you utilize Terraform to configure your workspace declaratively instead of relying on the Hookdeck dashboard. You can run Terraform in your CI/CD pipeline and maintain Hookdeck workspace configuration programmatically as part of your deployment workflow. To get started, follow its documentation to [install Terraform CLI locally](https://developer.hashicorp.com/terraform/downloads). ## Tutorial -Before you begin, make sure you have Terraform CLI installed locally and a Hookdeck API Key obtained from [the dashboard](https://dashboard/hookdeck.com/workspace/secrets). +Before you begin, make sure you have [Terraform CLI](https://developer.hashicorp.com/terraform/downloads) installed locally and a Hookdeck API Key obtained from [the dashboard](https://dashboard/hookdeck.com/workspace/secrets). ### Initialize Terraform -In a directory of your choice, create a Terraform config file `main.tf`. +In a directory of your choice, create a Terraform config file `main.tf`: ```hcl # main.tf @@ -46,17 +46,17 @@ provider "hookdeck" { } ``` --> Replace `` with your Hookdeck workspace API key. +Replace `` with your Hookdeck workspace API key. -After creating your basic configuration in HCL, initialize Terraform and ask it to apply the configuration to Cloudflare. +After creating your basic configuration in HCL, initialize Terraform and ask it to apply the configuration to Hookdeck. ```sh $ terraform init ``` -Running `terraform init` will download every required plugins in the configuration file, such as Hookdeck Terraform provider, to a local `.terraform`` directory. +Running `terraform init` will download the plugins required in the configuration file, such as the Hookdeck Terraform provider, to a local `.terraform` directory. -Afterwards, you can run `terraform plan` to confirm that you have Terraform properly installed. As you haven't added any resource to for Terraform to manage yet, it will indicate that there are no changes planned with the current state of your infrastructure. +Afterward, you can run `terraform plan` to confirm that you have Terraform properly installed. As you haven't added any resources for Terraform to manage yet, it will indicate that there are no planned changes with your infrastructure's current state. ``` $ terraform plan @@ -68,7 +68,7 @@ First, let's create a source resource with Terraform. You can add this resource ```hcl resource "hookdeck_source" "my_source" { - name = "my_source" + name = "my_source" } ``` @@ -116,11 +116,11 @@ $ terraform apply You can check the dashboard to confirm that a new source was created in your workspace. -To learn more about what options you have with Hookdeck's Source on Terraform, check out [its documentation here](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/source). +To learn more about what options you have with Hookdeck's Source on Terraform, check out the [`hookdeck_source` docs](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/source). ### Destination -Here's what a simple destination resource should look with Terraform +Next, add a simple destination resource: ```hcl resource "hookdeck_destination" "my_destination" { @@ -131,13 +131,13 @@ resource "hookdeck_destination" "my_destination" { This is a Mock destination which will accepts all of your events so you can inspect on Hookdeck's dashboard. -Similarly, you can run `terraform apply` to create your new destination. As you should see, when running `terraform apply`, Terraform will show the plan and ask for your confirmation before executing it, so you don't need to run `terraform plan` beforehand. +Now, run `terraform apply` to create your new destination. Terraform will show the plan and ask for your confirmation before executing it, so you don't need to run `terraform plan` beforehand. -To learn more about what options you have with Hookdeck's Destination on Terraform, check out [its documentation here](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/destination). +To learn more about what options you have with Hookdeck's Destination on Terraform, check out the [`hookdeck_destination` docs](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/destination). ### Connection -Lastly, you can create a Hookdeck connection to connect your newly created source and destination. +Lastly, define a Hookdeck connection to connect the source and destination: ```hcl resource "hookdeck_connection" "my_connection" { @@ -146,15 +146,17 @@ resource "hookdeck_connection" "my_connection" { } ``` -To learn more about what options you have with Hookdeck's Connection on Terraform, check out [its documentation here](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/connection). +As before, run `terraform apply` to review the plan and apply the changes. + +To learn more about what options you have with Hookdeck's Connection on Terraform, check the [`hookdeck_connection` docs](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/connection). ### Summary -In this tutorial, you have +In this tutorial, you have: -- installed Terraform CLI locally and initialized a Terraform project with Hookdeck provider with `terraform init` -- written the configuration code for a Hookdeck source, destination, and connection using Terraform's own declarative programming language HCL -- reviewed and executed the Terraform plan with `terraform plan` and `terraform apply` +- Installed Terraform CLI locally and initialized a Terraform project with Hookdeck provider with `terraform init` +- Written the configuration code for a Hookdeck source, destination, and connection using Terraform's declarative programming language, HCL +- Reviewed and executed the Terraform plan with `terraform plan` and `terraform apply` Here's the final `main.tf` file: diff --git a/templates/guides/register-external-webhooks.md b/templates/guides/register-external-webhooks.md index e7f4b3b..c4876e4 100644 --- a/templates/guides/register-external-webhooks.md +++ b/templates/guides/register-external-webhooks.md @@ -5,11 +5,13 @@ description: "Register External Webhooks with Hookdeck Provider" # Register External Webhooks -Hookdeck Terraform provider provides a solution to help register and unregister webhooks with your providers. It's provider-agnostic, so as long as there's an endpoint to manage webhooks programmatically, you should be able to configure it as part of your workflow. +The Hookdeck Terraform provider supports registering and unregistering webhooks with your external service providers, such as Stripe, Shopify, etc. It's service-agnostic, so if there's an endpoint to manage webhooks programmatically, you should be able to configure it as part of your workflow. ## Setup -For example, let's say you're using Stripe for payment and want to listen to `charge.succeeded` and `charge.failed` webhook events. Let's start with connection to start listening to incoming webhooks from Stripe. +For example, let's say you're using Stripe for payment and want to listen to `charge.succeeded` and `charge.failed` webhook events. + +Let's start with a Hookdeck connection to start listening to incoming webhooks from Stripe: ```hcl resource "hookdeck_source" "stripe" { @@ -29,7 +31,7 @@ resource "hookdeck_connection" "stripe_payment_service" { ## Register Stripe webhook -Stripe provides API endpoints to [create a new webhook](https://stripe.com/docs/api/webhook_endpoints/create) and [delete existing webhook](https://stripe.com/docs/api/webhook_endpoints/delete) which we will use in this example. +Stripe provides API endpoints to [create a new webhook](https://stripe.com/docs/api/webhook_endpoints/create) and [delete an existing webhook](https://stripe.com/docs/api/webhook_endpoints/delete), which we will use in this example. ```hcl resource "webhook_registration" "stripe" { @@ -64,7 +66,7 @@ resource "webhook_registration" "stripe" { } ``` -For many API, you will need the ID of the registered webhook to unregister. You can usually get the ID of the newly registered webhook from the register API response itself. Because of that, Hookdeck Terraform provider will save that response for use in the `unregister` flow. The string values when you configure your `unregister` property are string templates where you'll have access to `.register.response` data which is the HTTP response from the original registration API request. +For many APIs, you will need the ID of the registered webhook to unregister. You can usually get the ID of the newly registered webhook from the register API response itself. Because of that, the Hookdeck Terraform provider will save that response for use in the `unregister` flow. When configuring your `unregister` property, the string values are string templates where you'll have access to `.register.response` data, which is the HTTP response from the original registration API request. ## Use webhook secret to verify with Hookdeck @@ -81,9 +83,9 @@ resource "hookdeck_source_verification" "stripe_verification" { } ``` -As mentioned in the section earlier, the provider will save the response from the registration request to be used later (unregister flow). For some API, that response will also contain some secret information that you can use for verification purposes. As the `webhook_registration` is provider-agnostic, it saves the response in a strigified JSON with 2 fields "body" and "headers". When using that data in the unregistration flow, the provider constructs that response and use it in the template for you to use. When using it in other resources, you will need to decode the stringified JSON using [`jsondecode`](https://developer.hashicorp.com/terraform/language/functions/jsondecode) like the example above. +As mentioned in the section earlier, the provider will save the response from the registration request to be used later (unregister flow). For some APIs, that response will also contain secret information you can use for verification purposes. As the `webhook_registration` is provider-agnostic, it saves the response in a stringified JSON with two fields, "body" and "headers". When using that data in the unregister flow, the provider constructs that response and uses it in the template. When using the response in other resources, you will need to decode the stringified JSON using [`jsondecode`](https://developer.hashicorp.com/terraform/language/functions/jsondecode) like the example above. -Putting everything together, to register Stripe webhook with Hookdeck source with source verification, here's how your Terraform code would look like: +Putting everything together to register Stripe webhook with Hookdeck source with source verification, here's how your Terraform code will look: ```hcl # Configure Hookdeck source, destination, and connection diff --git a/templates/guides/rules.md b/templates/guides/rules.md index 1dba951..74fd1ec 100644 --- a/templates/guides/rules.md +++ b/templates/guides/rules.md @@ -17,9 +17,9 @@ The retry rule determines the rate and limit of [automatic retries](automaticall | Interval | The delay between each automatic retry | | Count | The number of automatic retries Hookdeck will attempt after an event fails | -> Automatic retries max out after one week, or {% $MAX_AUTOMATIC_RETRY_ATTEMPTS %} attempts – whichever comes first. Events can be [manually retried](manually-retry-events) after exceeding this limit. +> Automatic retries max out after one week, or {% $MAX_AUTOMATIC_RETRY_ATTEMPTS %} attempts – whichever comes first. Events can be [manually retried](https://hookdeck.com/docs/manually-retry-events) after exceeding this limit. -Here's how a connection with a linear retry strategy with 5 attempts per hour should look like: +Here's what a connection with a linear retry strategy with five attempts per hour looks like: ```hcl resource "hookdeck_connection" "my_connection" { @@ -41,7 +41,7 @@ resource "hookdeck_connection" "my_connection" { The delay rule allows you to introduce a delay between the moment Hookdeck receives an event, and when it's forwarded to your destination. -Here's how a connection with a 10-second delay rule look like: +Here's how to configure a connection with a 10-second delay: ```hcl resource "hookdeck_connection" "my_connection" { @@ -59,7 +59,7 @@ resource "hookdeck_connection" "my_connection" { ## Filter rule -The filter rule allows you to route webhooks differently based on the contents of their `Headers`, `Body`, `Query`, and/or `Path`. +The filter rule allows you to route webhooks based on the contents of their `Headers`, `Body`, `Query`, and/or `Path`. For more information on how to set up filters, see our [filter documentation](https://hookdeck.com/docs/filters). @@ -134,9 +134,9 @@ resource "hookdeck_connection" "my_connection" { The transformation rule allows you to modify the payload of a webhook before it gets delivered to a destination. -For more information on how to set up transformations, see our [transformation documentation](https://hookdeck.com/docs/transformations). +For more information on how to set up transformations, see the [Hookdeck transformation documentation](https://hookdeck.com/docs/transformations). -To use transformation with Terraform, you need to create a new transformation before using it with your connection. Here's how that should look: +To use transformation with Terraform, you must create a new transformation before using it with your connection. Here's an example transformation: ```hcl resource "hookdeck_transformation" "my_transformation" { @@ -157,7 +157,7 @@ resource "hookdeck_connection" "my_connection" { } ``` -As the transformation code also expects a stringified function handler, you can also keep your transformation code in a separate file. +As the transformation code also expects a stringified function handler, you can also keep your transformation code in a separate file: ```hcl resource "hookdeck_transformation" "my_transformation" { @@ -166,4 +166,4 @@ resource "hookdeck_transformation" "my_transformation" { } ``` --> With Hookdeck Terraform provider, you can keep your filter and transformation code in version control. +With the Hookdeck Terraform provider, you can keep your filter and transformation code in version control. From 5ece299e23fd4ec3100d5dcc22fa4a3e4470b09c Mon Sep 17 00:00:00 2001 From: Phil Leggetter Date: Mon, 23 Oct 2023 21:54:36 +0100 Subject: [PATCH 4/8] chore: remove duplicate Terraform CLI install prerequisite --- templates/guides/getting-started.md | 1 - 1 file changed, 1 deletion(-) diff --git a/templates/guides/getting-started.md b/templates/guides/getting-started.md index f8355bb..3003311 100644 --- a/templates/guides/getting-started.md +++ b/templates/guides/getting-started.md @@ -19,7 +19,6 @@ Visit the [Hookdeck documentation](https://hookdeck.com/docs/introduction) to le The Hookdeck Terraform provider helps you utilize Terraform to configure your workspace declaratively instead of relying on the Hookdeck dashboard. You can run Terraform in your CI/CD pipeline and maintain Hookdeck workspace configuration programmatically as part of your deployment workflow. -To get started, follow its documentation to [install Terraform CLI locally](https://developer.hashicorp.com/terraform/downloads). ## Tutorial From d2ba014ecdeec43cb4b3f25caff5f0dd124e503f Mon Sep 17 00:00:00 2001 From: Phil Leggetter Date: Mon, 23 Oct 2023 21:55:42 +0100 Subject: [PATCH 5/8] chore: add domain to docs link --- templates/guides/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/guides/rules.md b/templates/guides/rules.md index 74fd1ec..7cee2ed 100644 --- a/templates/guides/rules.md +++ b/templates/guides/rules.md @@ -9,7 +9,7 @@ A rule is a piece of instructional logic that dictates the behavior of events ro ## Retry rule -The retry rule determines the rate and limit of [automatic retries](automatically-retry-events) on failed events. +The retry rule determines the rate and limit of [automatic retries](https://hookdeck.com/docs/automatically-retry-events) on failed events. | Retry Rule Element | Explanation | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | From 5d4087060758fa5a66046a969b12bf86dc1fabca Mon Sep 17 00:00:00 2001 From: Phil Leggetter Date: Tue, 24 Oct 2023 10:32:19 +0100 Subject: [PATCH 6/8] chore: add transformation js example --- templates/guides/rules.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/templates/guides/rules.md b/templates/guides/rules.md index 7cee2ed..70e1501 100644 --- a/templates/guides/rules.md +++ b/templates/guides/rules.md @@ -166,4 +166,10 @@ resource "hookdeck_transformation" "my_transformation" { } ``` +With /transformations/my_transformation.js as follows: + +```js +addHandler('transform', (request, context) => request); +``` + With the Hookdeck Terraform provider, you can keep your filter and transformation code in version control. From 22ca5958188a491bfdd84ceb0e4d51c29de8fcf2 Mon Sep 17 00:00:00 2001 From: Phil Leggetter Date: Tue, 24 Oct 2023 10:32:33 +0100 Subject: [PATCH 7/8] chore: format rules.md --- templates/guides/rules.md | 53 +++++++++++++++++++++++++++------------ 1 file changed, 37 insertions(+), 16 deletions(-) diff --git a/templates/guides/rules.md b/templates/guides/rules.md index 70e1501..3bcc586 100644 --- a/templates/guides/rules.md +++ b/templates/guides/rules.md @@ -5,11 +5,14 @@ description: "Connection Rules" # Hookdeck Rules -A rule is a piece of instructional logic that dictates the behavior of events routed through a connection. There are 4 types of rules in Hookdeck: +A rule is a piece of instructional logic that dictates the behavior of events +routed through a connection. There are 4 types of rules in Hookdeck: ## Retry rule -The retry rule determines the rate and limit of [automatic retries](https://hookdeck.com/docs/automatically-retry-events) on failed events. +The retry rule determines the rate and limit of +[automatic retries](https://hookdeck.com/docs/automatically-retry-events) on +failed events. | Retry Rule Element | Explanation | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -17,9 +20,13 @@ The retry rule determines the rate and limit of [automatic retries](https://hook | Interval | The delay between each automatic retry | | Count | The number of automatic retries Hookdeck will attempt after an event fails | -> Automatic retries max out after one week, or {% $MAX_AUTOMATIC_RETRY_ATTEMPTS %} attempts – whichever comes first. Events can be [manually retried](https://hookdeck.com/docs/manually-retry-events) after exceeding this limit. +> Automatic retries max out after one week, or +> {% $MAX_AUTOMATIC_RETRY_ATTEMPTS %} attempts – whichever comes first. Events +> can be [manually retried](https://hookdeck.com/docs/manually-retry-events) +> after exceeding this limit. -Here's what a connection with a linear retry strategy with five attempts per hour looks like: +Here's what a connection with a linear retry strategy with five attempts per +hour looks like: ```hcl resource "hookdeck_connection" "my_connection" { @@ -39,7 +46,8 @@ resource "hookdeck_connection" "my_connection" { ## Delay rule -The delay rule allows you to introduce a delay between the moment Hookdeck receives an event, and when it's forwarded to your destination. +The delay rule allows you to introduce a delay between the moment Hookdeck +receives an event, and when it's forwarded to your destination. Here's how to configure a connection with a 10-second delay: @@ -59,9 +67,11 @@ resource "hookdeck_connection" "my_connection" { ## Filter rule -The filter rule allows you to route webhooks based on the contents of their `Headers`, `Body`, `Query`, and/or `Path`. +The filter rule allows you to route webhooks based on the contents of their +`Headers`, `Body`, `Query`, and/or `Path`. -For more information on how to set up filters, see our [filter documentation](https://hookdeck.com/docs/filters). +For more information on how to set up filters, see our +[filter documentation](https://hookdeck.com/docs/filters). Here's how a connection with a filter look like: @@ -90,9 +100,13 @@ resource "hookdeck_connection" "my_connection" { } ``` -As the Terraform provider expects a stringified JSON value for the JSON rule, there are some other approaches that you can use to configure your connection to your liking: +As the Terraform provider expects a stringified JSON value for the JSON rule, +there are some other approaches that you can use to configure your connection to +your liking: -- Using Terraform's [`jsonencoded`](https://developer.hashicorp.com/terraform/language/functions/jsonencode) for better readbility inline: +- Using Terraform's + [`jsonencoded`](https://developer.hashicorp.com/terraform/language/functions/jsonencode) + for better readbility inline: ```hcl resource "hookdeck_connection" "my_connection" { @@ -112,7 +126,9 @@ resource "hookdeck_connection" "my_connection" { } ``` -- Using Terraform's [`file`](https://developer.hashicorp.com/terraform/language/functions/file) to write your filter code in a separate file: +- Using Terraform's + [`file`](https://developer.hashicorp.com/terraform/language/functions/file) to + write your filter code in a separate file: ```hcl resource "hookdeck_connection" "my_connection" { @@ -132,11 +148,14 @@ resource "hookdeck_connection" "my_connection" { ## Transformation rule -The transformation rule allows you to modify the payload of a webhook before it gets delivered to a destination. +The transformation rule allows you to modify the payload of a webhook before it +gets delivered to a destination. -For more information on how to set up transformations, see the [Hookdeck transformation documentation](https://hookdeck.com/docs/transformations). +For more information on how to set up transformations, see the +[Hookdeck transformation documentation](https://hookdeck.com/docs/transformations). -To use transformation with Terraform, you must create a new transformation before using it with your connection. Here's an example transformation: +To use transformation with Terraform, you must create a new transformation +before using it with your connection. Here's an example transformation: ```hcl resource "hookdeck_transformation" "my_transformation" { @@ -157,7 +176,8 @@ resource "hookdeck_connection" "my_connection" { } ``` -As the transformation code also expects a stringified function handler, you can also keep your transformation code in a separate file: +As the transformation code also expects a stringified function handler, you can +also keep your transformation code in a separate file: ```hcl resource "hookdeck_transformation" "my_transformation" { @@ -169,7 +189,8 @@ resource "hookdeck_transformation" "my_transformation" { With /transformations/my_transformation.js as follows: ```js -addHandler('transform', (request, context) => request); +addHandler("transform", (request, context) => request); ``` -With the Hookdeck Terraform provider, you can keep your filter and transformation code in version control. +With the Hookdeck Terraform provider, you can keep your filter and +transformation code in version control. From fd67cf6bd79594881e5d574057276f6c8bd7e1f8 Mon Sep 17 00:00:00 2001 From: Phil Leggetter Date: Tue, 24 Oct 2023 10:45:00 +0100 Subject: [PATCH 8/8] chore: generate docs --- docs/guides/getting-started.md | 43 +++++++++-------- docs/guides/register-external-webhooks.md | 14 +++--- docs/guides/rules.md | 59 +++++++++++++++++------ 3 files changed, 73 insertions(+), 43 deletions(-) diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index 770ef41..3003311 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -7,9 +7,9 @@ description: "Getting Started with Hookdeck Provider" ## Hookdeck -Hookdeck is a prebuilt webhook infrastructure. It gives developers the tooling they need to monitor and troubleshoot all their inbound webhooks. +The Hookdeck Event Gateway enables engineering teams to build, deploy, observe, and scale event-driven applications. -Once integrated, Hookdeck unlocks an entire suite of tools: [alerting](https://hookdeck.com/docs/notifications), [rate limiting](https://hookdeck.com/docs/set-a-rate-limit), [automatic retries](https://hookdeck.com/docs/automatically-retry-events), [one-to-many delivery](https://hookdeck.com/docs/create-a-destination), [payload transformations](https://hookdeck.com/docs/transformations), local testing via the [CLI](https://hookdeck.com/docs/using-the-cli), a feature-rich [API](https://hookdeck.com/docs/using-the-api), and more. It acts as a proxy – routing webhooks from any [source](https://hookdeck.com/docs/sources) to a specified [destination](destinations) – so you can spend less time maintaining an asynchronous event infrastructure and more time building the features your users care about. +Once integrated, Hookdeck unlocks an entire suite of tools: [alerting](https://hookdeck.com/docs/notifications), [rate limiting](https://hookdeck.com/docs/set-a-rate-limit), [automatic retries](https://hookdeck.com/docs/automatically-retry-events), [one-to-many delivery](https://hookdeck.com/docs/create-a-destination), [payload transformations](https://hookdeck.com/docs/transformations), local testing via the [CLI](https://hookdeck.com/docs/using-the-cli), a feature-rich [API](https://hookdeck.com/docs/using-the-api), and more. It acts as a proxy – routing webhooks from any [source](https://hookdeck.com/docs/sources) to a specified [destination](destinations). Visit the [Hookdeck documentation](https://hookdeck.com/docs/introduction) to learn more. @@ -17,17 +17,16 @@ Visit the [Hookdeck documentation](https://hookdeck.com/docs/introduction) to le [Terraform](https://developer.hashicorp.com/terraform/intro) is an open-source Infrastructure as Code (IaC) tool that allows you to define and manage infrastructure resources using HashiCorp Configuration Language (HCL). It can be used to manage a wide range of resources, including servers, storage, networks, and cloud services. Terraform is a popular choice for infrastructure automation because it is easy to use, flexible, and powerful. -Hookdeck provides a Terraform provider that helps you utilize Terraform to configure your workspace declaratively instead of relying on the dashboard. You can run Terraform in your CI/CD pipeline and maintain Hookdeck workspace configuration programmatically as part of your deployment workflow. +The Hookdeck Terraform provider helps you utilize Terraform to configure your workspace declaratively instead of relying on the Hookdeck dashboard. You can run Terraform in your CI/CD pipeline and maintain Hookdeck workspace configuration programmatically as part of your deployment workflow. -To get started, follow its documentation to [install Terraform CLI locally](https://developer.hashicorp.com/terraform/downloads). ## Tutorial -Before you begin, make sure you have Terraform CLI installed locally and a Hookdeck API Key obtained from [the dashboard](https://dashboard/hookdeck.com/workspace/secrets). +Before you begin, make sure you have [Terraform CLI](https://developer.hashicorp.com/terraform/downloads) installed locally and a Hookdeck API Key obtained from [the dashboard](https://dashboard/hookdeck.com/workspace/secrets). ### Initialize Terraform -In a directory of your choice, create a Terraform config file `main.tf`. +In a directory of your choice, create a Terraform config file `main.tf`: ```hcl # main.tf @@ -46,17 +45,17 @@ provider "hookdeck" { } ``` --> Replace `` with your Hookdeck workspace API key. +Replace `` with your Hookdeck workspace API key. -After creating your basic configuration in HCL, initialize Terraform and ask it to apply the configuration to Cloudflare. +After creating your basic configuration in HCL, initialize Terraform and ask it to apply the configuration to Hookdeck. ```sh $ terraform init ``` -Running `terraform init` will download every required plugins in the configuration file, such as Hookdeck Terraform provider, to a local `.terraform`` directory. +Running `terraform init` will download the plugins required in the configuration file, such as the Hookdeck Terraform provider, to a local `.terraform` directory. -Afterwards, you can run `terraform plan` to confirm that you have Terraform properly installed. As you haven't added any resource to for Terraform to manage yet, it will indicate that there are no changes planned with the current state of your infrastructure. +Afterward, you can run `terraform plan` to confirm that you have Terraform properly installed. As you haven't added any resources for Terraform to manage yet, it will indicate that there are no planned changes with your infrastructure's current state. ``` $ terraform plan @@ -68,7 +67,7 @@ First, let's create a source resource with Terraform. You can add this resource ```hcl resource "hookdeck_source" "my_source" { - name = "my_source" + name = "my_source" } ``` @@ -116,11 +115,11 @@ $ terraform apply You can check the dashboard to confirm that a new source was created in your workspace. -To learn more about what options you have with Hookdeck's Source on Terraform, check out [its documentation here](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/source). +To learn more about what options you have with Hookdeck's Source on Terraform, check out the [`hookdeck_source` docs](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/source). ### Destination -Here's what a simple destination resource should look with Terraform +Next, add a simple destination resource: ```hcl resource "hookdeck_destination" "my_destination" { @@ -131,13 +130,13 @@ resource "hookdeck_destination" "my_destination" { This is a Mock destination which will accepts all of your events so you can inspect on Hookdeck's dashboard. -Similarly, you can run `terraform apply` to create your new destination. As you should see, when running `terraform apply`, Terraform will show the plan and ask for your confirmation before executing it, so you don't need to run `terraform plan` beforehand. +Now, run `terraform apply` to create your new destination. Terraform will show the plan and ask for your confirmation before executing it, so you don't need to run `terraform plan` beforehand. -To learn more about what options you have with Hookdeck's Destination on Terraform, check out [its documentation here](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/destination). +To learn more about what options you have with Hookdeck's Destination on Terraform, check out the [`hookdeck_destination` docs](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/destination). ### Connection -Lastly, you can create a Hookdeck connection to connect your newly created source and destination. +Lastly, define a Hookdeck connection to connect the source and destination: ```hcl resource "hookdeck_connection" "my_connection" { @@ -146,15 +145,17 @@ resource "hookdeck_connection" "my_connection" { } ``` -To learn more about what options you have with Hookdeck's Connection on Terraform, check out [its documentation here](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/connection). +As before, run `terraform apply` to review the plan and apply the changes. + +To learn more about what options you have with Hookdeck's Connection on Terraform, check the [`hookdeck_connection` docs](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs/resources/connection). ### Summary -In this tutorial, you have +In this tutorial, you have: -- installed Terraform CLI locally and initialized a Terraform project with Hookdeck provider with `terraform init` -- written the configuration code for a Hookdeck source, destination, and connection using Terraform's own declarative programming language HCL -- reviewed and executed the Terraform plan with `terraform plan` and `terraform apply` +- Installed Terraform CLI locally and initialized a Terraform project with Hookdeck provider with `terraform init` +- Written the configuration code for a Hookdeck source, destination, and connection using Terraform's declarative programming language, HCL +- Reviewed and executed the Terraform plan with `terraform plan` and `terraform apply` Here's the final `main.tf` file: diff --git a/docs/guides/register-external-webhooks.md b/docs/guides/register-external-webhooks.md index e7f4b3b..c4876e4 100644 --- a/docs/guides/register-external-webhooks.md +++ b/docs/guides/register-external-webhooks.md @@ -5,11 +5,13 @@ description: "Register External Webhooks with Hookdeck Provider" # Register External Webhooks -Hookdeck Terraform provider provides a solution to help register and unregister webhooks with your providers. It's provider-agnostic, so as long as there's an endpoint to manage webhooks programmatically, you should be able to configure it as part of your workflow. +The Hookdeck Terraform provider supports registering and unregistering webhooks with your external service providers, such as Stripe, Shopify, etc. It's service-agnostic, so if there's an endpoint to manage webhooks programmatically, you should be able to configure it as part of your workflow. ## Setup -For example, let's say you're using Stripe for payment and want to listen to `charge.succeeded` and `charge.failed` webhook events. Let's start with connection to start listening to incoming webhooks from Stripe. +For example, let's say you're using Stripe for payment and want to listen to `charge.succeeded` and `charge.failed` webhook events. + +Let's start with a Hookdeck connection to start listening to incoming webhooks from Stripe: ```hcl resource "hookdeck_source" "stripe" { @@ -29,7 +31,7 @@ resource "hookdeck_connection" "stripe_payment_service" { ## Register Stripe webhook -Stripe provides API endpoints to [create a new webhook](https://stripe.com/docs/api/webhook_endpoints/create) and [delete existing webhook](https://stripe.com/docs/api/webhook_endpoints/delete) which we will use in this example. +Stripe provides API endpoints to [create a new webhook](https://stripe.com/docs/api/webhook_endpoints/create) and [delete an existing webhook](https://stripe.com/docs/api/webhook_endpoints/delete), which we will use in this example. ```hcl resource "webhook_registration" "stripe" { @@ -64,7 +66,7 @@ resource "webhook_registration" "stripe" { } ``` -For many API, you will need the ID of the registered webhook to unregister. You can usually get the ID of the newly registered webhook from the register API response itself. Because of that, Hookdeck Terraform provider will save that response for use in the `unregister` flow. The string values when you configure your `unregister` property are string templates where you'll have access to `.register.response` data which is the HTTP response from the original registration API request. +For many APIs, you will need the ID of the registered webhook to unregister. You can usually get the ID of the newly registered webhook from the register API response itself. Because of that, the Hookdeck Terraform provider will save that response for use in the `unregister` flow. When configuring your `unregister` property, the string values are string templates where you'll have access to `.register.response` data, which is the HTTP response from the original registration API request. ## Use webhook secret to verify with Hookdeck @@ -81,9 +83,9 @@ resource "hookdeck_source_verification" "stripe_verification" { } ``` -As mentioned in the section earlier, the provider will save the response from the registration request to be used later (unregister flow). For some API, that response will also contain some secret information that you can use for verification purposes. As the `webhook_registration` is provider-agnostic, it saves the response in a strigified JSON with 2 fields "body" and "headers". When using that data in the unregistration flow, the provider constructs that response and use it in the template for you to use. When using it in other resources, you will need to decode the stringified JSON using [`jsondecode`](https://developer.hashicorp.com/terraform/language/functions/jsondecode) like the example above. +As mentioned in the section earlier, the provider will save the response from the registration request to be used later (unregister flow). For some APIs, that response will also contain secret information you can use for verification purposes. As the `webhook_registration` is provider-agnostic, it saves the response in a stringified JSON with two fields, "body" and "headers". When using that data in the unregister flow, the provider constructs that response and uses it in the template. When using the response in other resources, you will need to decode the stringified JSON using [`jsondecode`](https://developer.hashicorp.com/terraform/language/functions/jsondecode) like the example above. -Putting everything together, to register Stripe webhook with Hookdeck source with source verification, here's how your Terraform code would look like: +Putting everything together to register Stripe webhook with Hookdeck source with source verification, here's how your Terraform code will look: ```hcl # Configure Hookdeck source, destination, and connection diff --git a/docs/guides/rules.md b/docs/guides/rules.md index 1dba951..3bcc586 100644 --- a/docs/guides/rules.md +++ b/docs/guides/rules.md @@ -5,11 +5,14 @@ description: "Connection Rules" # Hookdeck Rules -A rule is a piece of instructional logic that dictates the behavior of events routed through a connection. There are 4 types of rules in Hookdeck: +A rule is a piece of instructional logic that dictates the behavior of events +routed through a connection. There are 4 types of rules in Hookdeck: ## Retry rule -The retry rule determines the rate and limit of [automatic retries](automatically-retry-events) on failed events. +The retry rule determines the rate and limit of +[automatic retries](https://hookdeck.com/docs/automatically-retry-events) on +failed events. | Retry Rule Element | Explanation | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -17,9 +20,13 @@ The retry rule determines the rate and limit of [automatic retries](automaticall | Interval | The delay between each automatic retry | | Count | The number of automatic retries Hookdeck will attempt after an event fails | -> Automatic retries max out after one week, or {% $MAX_AUTOMATIC_RETRY_ATTEMPTS %} attempts – whichever comes first. Events can be [manually retried](manually-retry-events) after exceeding this limit. +> Automatic retries max out after one week, or +> {% $MAX_AUTOMATIC_RETRY_ATTEMPTS %} attempts – whichever comes first. Events +> can be [manually retried](https://hookdeck.com/docs/manually-retry-events) +> after exceeding this limit. -Here's how a connection with a linear retry strategy with 5 attempts per hour should look like: +Here's what a connection with a linear retry strategy with five attempts per +hour looks like: ```hcl resource "hookdeck_connection" "my_connection" { @@ -39,9 +46,10 @@ resource "hookdeck_connection" "my_connection" { ## Delay rule -The delay rule allows you to introduce a delay between the moment Hookdeck receives an event, and when it's forwarded to your destination. +The delay rule allows you to introduce a delay between the moment Hookdeck +receives an event, and when it's forwarded to your destination. -Here's how a connection with a 10-second delay rule look like: +Here's how to configure a connection with a 10-second delay: ```hcl resource "hookdeck_connection" "my_connection" { @@ -59,9 +67,11 @@ resource "hookdeck_connection" "my_connection" { ## Filter rule -The filter rule allows you to route webhooks differently based on the contents of their `Headers`, `Body`, `Query`, and/or `Path`. +The filter rule allows you to route webhooks based on the contents of their +`Headers`, `Body`, `Query`, and/or `Path`. -For more information on how to set up filters, see our [filter documentation](https://hookdeck.com/docs/filters). +For more information on how to set up filters, see our +[filter documentation](https://hookdeck.com/docs/filters). Here's how a connection with a filter look like: @@ -90,9 +100,13 @@ resource "hookdeck_connection" "my_connection" { } ``` -As the Terraform provider expects a stringified JSON value for the JSON rule, there are some other approaches that you can use to configure your connection to your liking: +As the Terraform provider expects a stringified JSON value for the JSON rule, +there are some other approaches that you can use to configure your connection to +your liking: -- Using Terraform's [`jsonencoded`](https://developer.hashicorp.com/terraform/language/functions/jsonencode) for better readbility inline: +- Using Terraform's + [`jsonencoded`](https://developer.hashicorp.com/terraform/language/functions/jsonencode) + for better readbility inline: ```hcl resource "hookdeck_connection" "my_connection" { @@ -112,7 +126,9 @@ resource "hookdeck_connection" "my_connection" { } ``` -- Using Terraform's [`file`](https://developer.hashicorp.com/terraform/language/functions/file) to write your filter code in a separate file: +- Using Terraform's + [`file`](https://developer.hashicorp.com/terraform/language/functions/file) to + write your filter code in a separate file: ```hcl resource "hookdeck_connection" "my_connection" { @@ -132,11 +148,14 @@ resource "hookdeck_connection" "my_connection" { ## Transformation rule -The transformation rule allows you to modify the payload of a webhook before it gets delivered to a destination. +The transformation rule allows you to modify the payload of a webhook before it +gets delivered to a destination. -For more information on how to set up transformations, see our [transformation documentation](https://hookdeck.com/docs/transformations). +For more information on how to set up transformations, see the +[Hookdeck transformation documentation](https://hookdeck.com/docs/transformations). -To use transformation with Terraform, you need to create a new transformation before using it with your connection. Here's how that should look: +To use transformation with Terraform, you must create a new transformation +before using it with your connection. Here's an example transformation: ```hcl resource "hookdeck_transformation" "my_transformation" { @@ -157,7 +176,8 @@ resource "hookdeck_connection" "my_connection" { } ``` -As the transformation code also expects a stringified function handler, you can also keep your transformation code in a separate file. +As the transformation code also expects a stringified function handler, you can +also keep your transformation code in a separate file: ```hcl resource "hookdeck_transformation" "my_transformation" { @@ -166,4 +186,11 @@ resource "hookdeck_transformation" "my_transformation" { } ``` --> With Hookdeck Terraform provider, you can keep your filter and transformation code in version control. +With /transformations/my_transformation.js as follows: + +```js +addHandler("transform", (request, context) => request); +``` + +With the Hookdeck Terraform provider, you can keep your filter and +transformation code in version control.