Skip to content

Commit 7a08ee6

Browse files
alexluongleggetter
alexluong
and
leggetter
authored
feat: Add README and getting started docs (#6)
* docs: Add README and getting started docs * fix: Replace Ably references * chore: docs review updates * chore: remove duplicate Terraform CLI install prerequisite * chore: add domain to docs link * chore: add transformation js example * chore: format rules.md * chore: generate docs --------- Co-authored-by: Phil Leggetter <[email protected]>
1 parent de618de commit 7a08ee6

File tree

7 files changed

+1124
-0
lines changed

7 files changed

+1124
-0
lines changed

‎README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,55 @@
11
# Hookdeck Terraform Provider
2+
3+
_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)._
4+
5+
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.
6+
7+
## Installation
8+
9+
To install Hookdeck Terraform provider:
10+
11+
1. Obtain your Hookdeck API key from [the dashboard](https://dashboard.hookdeck.com/workspace/secrets)
12+
2. Add the following to your Terraform configuration file:
13+
14+
```hcl
15+
terraform {
16+
required_providers {
17+
hookdeck = {
18+
source = "hookdeck/hookdeck"
19+
version = "0.1.2"
20+
}
21+
}
22+
}
23+
24+
provider "hookdeck" {
25+
# set HOOKDECK_API_KEY env var or optionally specify the key in the provider configuration
26+
api_key = var.hookdeck_api_key
27+
}
28+
```
29+
30+
## Using the provider
31+
32+
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.
33+
34+
```hcl
35+
# Configure a source
36+
resource "hookdeck_source" "my_source" {
37+
name = "my_source"
38+
}
39+
40+
# Configure a destination
41+
resource "hookdeck_destination" "my_destination" {
42+
name = "my_destination"
43+
url = "https://mock.hookdeck.com"
44+
}
45+
46+
# Configure a connection
47+
resource "hookdeck_connection" "my_connection" {
48+
source_id = hookdeck_source.my_source.id
49+
destination_id = hookdeck_destination.my_destination.id
50+
}
51+
```
52+
53+
## Dependencies
54+
55+
This provider uses [Hookdeck API](https://hookdeck.com/api-ref) and [Hookdeck Go SDK](https://github.com/hookdeck/hookdeck-go-sdk) under the hood.

‎docs/guides/getting-started.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
page_title: "Getting Started"
3+
description: "Getting Started with Hookdeck Provider"
4+
---
5+
6+
# Getting Started with Hookdeck Provider
7+
8+
## Hookdeck
9+
10+
The Hookdeck Event Gateway enables engineering teams to build, deploy, observe, and scale event-driven applications.
11+
12+
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).
13+
14+
Visit the [Hookdeck documentation](https://hookdeck.com/docs/introduction) to learn more.
15+
16+
## Terraform
17+
18+
[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.
19+
20+
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.
21+
22+
23+
## Tutorial
24+
25+
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).
26+
27+
### Initialize Terraform
28+
29+
In a directory of your choice, create a Terraform config file `main.tf`:
30+
31+
```hcl
32+
# main.tf
33+
34+
terraform {
35+
required_providers {
36+
hookdeck = {
37+
source = "hookdeck/hookdeck"
38+
version = "~> 0.1"
39+
}
40+
}
41+
}
42+
43+
provider "hookdeck" {
44+
api_key = "<YOUR_API_KEY>"
45+
}
46+
```
47+
48+
Replace `<YOUR_API_KEY>` with your Hookdeck workspace API key.
49+
50+
After creating your basic configuration in HCL, initialize Terraform and ask it to apply the configuration to Hookdeck.
51+
52+
```sh
53+
$ terraform init
54+
```
55+
56+
Running `terraform init` will download the plugins required in the configuration file, such as the Hookdeck Terraform provider, to a local `.terraform` directory.
57+
58+
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.
59+
60+
```
61+
$ terraform plan
62+
```
63+
64+
### Source
65+
66+
First, let's create a source resource with Terraform. You can add this resource block to the end of your Terraform configuration file
67+
68+
```hcl
69+
resource "hookdeck_source" "my_source" {
70+
name = "my_source"
71+
}
72+
```
73+
74+
Now, try `terraform plan` again to see what Terraform may suggest
75+
76+
```sh
77+
$ terraform plan
78+
```
79+
80+
```
81+
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
82+
+ create
83+
84+
Terraform will perform the following actions:
85+
86+
# hookdeck_source.my_source will be created
87+
+ resource "hookdeck_source" "my_source" {
88+
+ allowed_http_methods = [
89+
+ "POST",
90+
+ "PUT",
91+
+ "PATCH",
92+
+ "DELETE",
93+
]
94+
+ archived_at = (known after apply)
95+
+ created_at = (known after apply)
96+
+ id = (known after apply)
97+
+ name = "my_source"
98+
+ team_id = (known after apply)
99+
+ updated_at = (known after apply)
100+
+ url = (known after apply)
101+
}
102+
103+
Plan: 1 to add, 0 to change, 0 to destroy.
104+
105+
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
106+
107+
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.
108+
```
109+
110+
You can execute this change and create a source in your workspace like so.
111+
112+
```sh
113+
$ terraform apply
114+
```
115+
116+
You can check the dashboard to confirm that a new source was created in your workspace.
117+
118+
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).
119+
120+
### Destination
121+
122+
Next, add a simple destination resource:
123+
124+
```hcl
125+
resource "hookdeck_destination" "my_destination" {
126+
name = "my_destination"
127+
url = "https://mock.hookdeck.com"
128+
}
129+
```
130+
131+
This is a Mock destination which will accepts all of your events so you can inspect on Hookdeck's dashboard.
132+
133+
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.
134+
135+
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).
136+
137+
### Connection
138+
139+
Lastly, define a Hookdeck connection to connect the source and destination:
140+
141+
```hcl
142+
resource "hookdeck_connection" "my_connection" {
143+
source_id = hookdeck_source.my_source.id
144+
destination_id = hookdeck_destination.my_destination.id
145+
}
146+
```
147+
148+
As before, run `terraform apply` to review the plan and apply the changes.
149+
150+
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).
151+
152+
### Summary
153+
154+
In this tutorial, you have:
155+
156+
- Installed Terraform CLI locally and initialized a Terraform project with Hookdeck provider with `terraform init`
157+
- Written the configuration code for a Hookdeck source, destination, and connection using Terraform's declarative programming language, HCL
158+
- Reviewed and executed the Terraform plan with `terraform plan` and `terraform apply`
159+
160+
Here's the final `main.tf` file:
161+
162+
```
163+
terraform {
164+
required_providers {
165+
hookdeck = {
166+
source = "hookdeck/hookdeck"
167+
version = "~> 0.1"
168+
}
169+
}
170+
}
171+
172+
provider "hookdeck" {
173+
api_key = "<YOUR_API_KEY>"
174+
}
175+
176+
resource "hookdeck_source" "my_source" {
177+
name = "my_source"
178+
}
179+
180+
resource "hookdeck_destination" "my_destination" {
181+
name = "my_destination"
182+
url = "https://mock.hookdeck.com"
183+
}
184+
185+
resource "hookdeck_connection" "my_connection" {
186+
source_id = hookdeck_source.my_source.id
187+
destination_id = hookdeck_destination.my_destination.id
188+
}
189+
```

‎docs/guides/register-external-webhooks.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
page_title: "Register External Webhooks"
3+
description: "Register External Webhooks with Hookdeck Provider"
4+
---
5+
6+
# Register External Webhooks
7+
8+
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.
9+
10+
## Setup
11+
12+
For example, let's say you're using Stripe for payment and want to listen to `charge.succeeded` and `charge.failed` webhook events.
13+
14+
Let's start with a Hookdeck connection to start listening to incoming webhooks from Stripe:
15+
16+
```hcl
17+
resource "hookdeck_source" "stripe" {
18+
name = "stripe"
19+
}
20+
21+
resource "hookdeck_destination" "payment_service" {
22+
name = "my_destination"
23+
url = "https://api.my-app.com/webhooks/stripe"
24+
}
25+
26+
resource "hookdeck_connection" "stripe_payment_service" {
27+
source_id = hookdeck_source.stripe.id
28+
destination_id = hookdeck_destination.payment_service.id
29+
}
30+
```
31+
32+
## Register Stripe webhook
33+
34+
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.
35+
36+
```hcl
37+
resource "webhook_registration" "stripe" {
38+
provider = hookdeck
39+
40+
register = {
41+
request = {
42+
method = "POST"
43+
url = "https://api.stripe.com/v1/webhook_endpoints"
44+
headers = jsonencode({
45+
"content-type" = "application/json"
46+
authorization = "Bearer <STRIPE_SECRET_KEY>"
47+
})
48+
body = jsonencode({
49+
url = hookdeck_source.stripe.url
50+
enabled_events = [
51+
"charge.failed",
52+
"charge.succeeded"
53+
]
54+
})
55+
}
56+
}
57+
unregister = {
58+
request = {
59+
method = "DELETE"
60+
url = "https://api.stripe.com/v1/webhook_endpoints/{{.register.response.body.id}}"
61+
headers = jsonencode({
62+
authorization = "Bearer <STRIPE_SECRET_KEY>"
63+
})
64+
}
65+
}
66+
}
67+
```
68+
69+
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.
70+
71+
## Use webhook secret to verify with Hookdeck
72+
73+
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:
74+
75+
```hcl
76+
resource "hookdeck_source_verification" "stripe_verification" {
77+
source_id = hookdeck_source.stripe.id
78+
verification = {
79+
stripe = {
80+
webhook_secret_key = jsondecode(webhook_registration.stripe.register.response).body.secret
81+
}
82+
}
83+
}
84+
```
85+
86+
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.
87+
88+
Putting everything together to register Stripe webhook with Hookdeck source with source verification, here's how your Terraform code will look:
89+
90+
```hcl
91+
# Configure Hookdeck source, destination, and connection
92+
93+
resource "hookdeck_source" "stripe" {
94+
name = "stripe"
95+
}
96+
97+
resource "hookdeck_destination" "payment_service" {
98+
name = "my_destination"
99+
url = "https://api.my-app.com/webhooks/stripe"
100+
}
101+
102+
resource "hookdeck_connection" "stripe_payment_service" {
103+
source_id = hookdeck_source.stripe.id
104+
destination_id = hookdeck_destination.payment_service.id
105+
}
106+
107+
# Register Stripe webhook
108+
109+
resource "webhook_registration" "stripe" {
110+
provider = hookdeck
111+
112+
register = {
113+
request = {
114+
method = "POST"
115+
url = "https://api.stripe.com/v1/webhook_endpoints"
116+
headers = jsonencode({
117+
"content-type" = "application/json"
118+
authorization = "Bearer <STRIPE_SECRET_KEY>"
119+
})
120+
body = jsonencode({
121+
url = hookdeck_source.stripe.url
122+
enabled_events = [
123+
"charge.failed",
124+
"charge.succeeded"
125+
]
126+
})
127+
}
128+
}
129+
unregister = {
130+
request = {
131+
method = "DELETE"
132+
url = "https://api.stripe.com/v1/webhook_endpoints/{{.register.response.body.id}}"
133+
headers = jsonencode({
134+
authorization = "Bearer <STRIPE_SECRET_KEY>"
135+
})
136+
}
137+
}
138+
}
139+
140+
# Configure source verification
141+
142+
resource "hookdeck_source_verification" "stripe_verification" {
143+
source_id = hookdeck_source.stripe.id
144+
verification = {
145+
stripe = {
146+
webhook_secret_key = jsondecode(webhook_registration.stripe.register.response).body.secret
147+
}
148+
}
149+
}
150+
```

0 commit comments

Comments
 (0)