Merge pull request #423 from golioth/transformer/webhook

golioth · Jul 25, 2024 · b128c1e · b128c1e
2 parents 401d126 + 4fad29c
commit b128c1e
Show file tree

Hide file tree

Showing 12 changed files with 130 additions and 6 deletions.
diff --git a/docs/data-routing/3-transformers/9-webhook.md b/docs/data-routing/3-transformers/9-webhook.md
@@ -0,0 +1,79 @@
+---
+title: webhook
+---
+
+|   |   |
+|---|:---:|
+|__Latest Version__| `v1.0.0` |
+|__Input Content Type__| Any |
+|__Output Content Type__| Any |
+
+:::usage
+Sending data to a webhook for transformation incurs usage costs after exceeding
+the free tier. See [Golioth pricing](https://golioth.io/pricing) for more
+information.
+:::
+
+The `webhook` transformer invokes an external API endpoint and, on success,
+replaces the data message content and content type with that of the response.
+
+:::info Tip
+The `webhook` transformer is not to be confused with the [`webhook` data
+destination](/data-routing/destinations/webhook). The transformer allows for
+modifying the content of a data message in a pipeline via an external API call,
+while the data destination delivers the event to an external location.
+:::
+
+### Parameters
+
+|Parameter|Type|Description|Required|
+|---|---|---|:---:|
+|`url`|`string`| The URL for the external webhook. |✅|
+|`headers`| Map (`string`: `string`)| Headers to be included in requests. ||
+
+### Example Secrets
+
+`API_KEY`
+```
+sup3rs3cr3t
+```
+
+### Example Usage
+
+```yaml
+    transformer:
+      type: webhook
+      version: v1
+      parameters:
+        url: https://my-webhook.example.com
+        headers:
+         x-api-key: $API_KEY
+```
+
+### Example Input
+
+```json
+{
+  "temp": 32
+}
+```
+
+The following headers will be present on all requests to external webhooks, in
+addition to any defined in the parameters.
+
+- `Ce-Source`: ID of device
+- `Ce-Subject`: ID of project
+- `Ce-Type`: Prefixed path (if path is `/sensor`, the value will be
+  `io.golioth.data.v1/.s/sensor`)
+- `Content-Type`: the content type of the data message payload
+
+### Example Output
+
+In this example, the webhook converts Celsius temperature readings to
+Fahrenheit.
+
+```json
+{
+  "temp": 89.6
+}
+```
diff --git a/docs/data-routing/4-destinations/1-lightdb-stream.md b/docs/data-routing/4-destinations/1-lightdb-stream.md
@@ -7,6 +7,11 @@ title: lightdb-stream
 |__Latest Version__| `v1.0.0` |
 |__Input Content Type__| `application/json` |
 
+:::usage
+Sending data to LightDB Stream incurs usage costs after exceeding the free tier.
+See [Golioth pricing](https://golioth.io/pricing) for more information.
+:::
+
 The LightDB Stream destination sends data to [LightDB
 Stream](/application-services/lightdb-stream). Data must have arrived as or been
 transformed into JSON in order to be successfully delivered to LightDB Stream.

diff --git a/docs/data-routing/4-destinations/10-aws-s3.md b/docs/data-routing/4-destinations/10-aws-s3.md
@@ -7,6 +7,11 @@ title: aws-s3
 |__Latest Version__| `v1.0.0` |
 |__Input Content Type__| Any |
 
+:::usage
+Sending data to S3 incurs usage costs after exceeding the free tier. See
+[Golioth pricing](https://golioth.io/pricing) for more information.
+:::
+
 The `aws-s3` destination sends data to an [Amazon Web Services
 S3](https://aws.amazon.com/s3/) bucket.
 

diff --git a/docs/data-routing/4-destinations/11-kafka.md b/docs/data-routing/4-destinations/11-kafka.md
@@ -7,6 +7,11 @@ title: kafka
 |__Latest Version__| `v1.0.0` |
 |__Input Content Type__| Any |
 
+:::usage
+Sending data to Kafka incurs usage costs after exceeding the free tier. See
+[Golioth pricing](https://golioth.io/pricing) for more information.
+:::
+
 The `kafka` destination sends data to a [Kafka](https://kafka.apache.org/)
 cluster.
 

diff --git a/docs/data-routing/4-destinations/2-mongodb.md b/docs/data-routing/4-destinations/2-mongodb.md
@@ -7,6 +7,11 @@ title: mongodb
 |__Latest Version__| `v1.0.0` |
 |__Input Content Type__| `application/json` |
 
+:::usage
+Sending data to MongoDB incurs usage costs after exceeding the free tier. See
+[Golioth pricing](https://golioth.io/pricing) for more information.
+:::
+
 The `mongodb` destination sends data to a [MongoDB Time
 Series](https://www.mongodb.com/products/capabilities/time-series) collection.
 Data must be supplied as JSON, which will be transformed to BSON after metadata

diff --git a/docs/data-routing/4-destinations/3-influxdb.md b/docs/data-routing/4-destinations/3-influxdb.md
@@ -7,6 +7,11 @@ title: influxdb
 |__Latest Version__| `v1.0.0` |
 |__Input Content Type__| `application/json` |
 
+:::usage
+Sending data to InfluxDB incurs usage costs after exceeding the free tier. See
+[Golioth pricing](https://golioth.io/pricing) for more information.
+:::
+
 The `influxdb` destination sends data to an
 [InfluxDB](https://www.influxdata.com/) bucket. Data must be supplied as JSON,
 which will be transformed to [line

diff --git a/docs/data-routing/4-destinations/4-webhook.md b/docs/data-routing/4-destinations/4-webhook.md
@@ -7,14 +7,19 @@ title: webhook
 |__Latest Version__| `v1.0.0` |
 |__Input Content Type__| Any |
 
+:::usage
+Sending data to a webhook incurs usage costs after exceeding the free tier. See
+[Golioth pricing](https://golioth.io/pricing) for more information.
+:::
+
 The `webhook` destination sends data via a `POST` request to the provided URL,
 with the supplied headers.
 
 ### Parameters
 
 |Parameter|Type|Description|Required|
 |---|---|---|:---:|
-|`url`|`string`| The connection string for a MongoDB instance. |✅|
+|`url`|`string`| The URL for the external webhook. |✅|
 |`headers`| Map (`string`: `string`)| Headers to be included in requests. ||
 
 ### Example Secrets

diff --git a/docs/data-routing/4-destinations/5-azure-event-hubs.md b/docs/data-routing/4-destinations/5-azure-event-hubs.md
@@ -7,6 +7,11 @@ title: azure-event-hubs
 |__Latest Version__| `v1.0.0` |
 |__Input Content Type__| Any |
 
+:::usage
+Sending data to Azure Event Hubs incurs usage costs after exceeding the free
+tier. See [Golioth pricing](https://golioth.io/pricing) for more information.
+:::
+
 The `azure-event-hubs` destination sends data to an [Azure Event
 Hubs](https://azure.microsoft.com/products/event-hubs) event hub or topic.
 

diff --git a/docs/data-routing/4-destinations/6-aws-sqs.md b/docs/data-routing/4-destinations/6-aws-sqs.md
@@ -7,6 +7,11 @@ title: aws-sqs
 |__Latest Version__| `v1.0.0` |
 |__Input Content Type__| Any |
 
+:::usage
+Sending data to AWS SQS incurs usage costs after exceeding the free tier. See
+[Golioth pricing](https://golioth.io/pricing) for more information.
+:::
+
 The `aws-sqs` destination sends data to an [Amazon Web Services Simple Queue
 Service](https://aws.amazon.com/sqs/) queue.
 

diff --git a/docs/data-routing/4-destinations/7-gcp-pubsub.md b/docs/data-routing/4-destinations/7-gcp-pubsub.md
@@ -7,6 +7,11 @@ title: gcp-pubsub
 |__Latest Version__| `v1.0.0` |
 |__Input Content Type__| Any |
 
+:::usage
+Sending data to GCP PubSub incurs usage costs after exceeding the free tier. See
+[Golioth pricing](https://golioth.io/pricing) for more information.
+:::
+
 The `gcp-pubsub` destination sends data to a [Google Cloud Platform PubSub](https://cloud.google.com/pubsub) topic.
 
 ### Parameters

diff --git a/docs/data-routing/4-destinations/9-memfault.md b/docs/data-routing/4-destinations/9-memfault.md
@@ -7,6 +7,11 @@ title: memfault
 |__Latest Version__| `v1.0.0` |
 |__Input Content Type__| `application/octet-stream` |
 
+:::usage
+Sending data to Memfault incurs usage costs after exceeding the free tier. See
+[Golioth pricing](https://golioth.io/pricing) for more information.
+:::
+
 The `memfault` destination uploads [chunk
 data](https://docs.memfault.com/docs/mcu/data-from-firmware-to-the-cloud/) to
 [Memfault](https://memfault.com/).

diff --git a/docs/data-routing/4-destinations/README.md b/docs/data-routing/4-destinations/README.md
@@ -5,11 +5,6 @@ title: Destinations
 Destinations are used to deliver data to external locations. A single pipeline
 may deliver data to multiple destinations.
 
-:::usage
-Sending data to a destination incurs usage costs after exceeding the free tier.
-See [Golioth pricing](https://golioth.io/pricing) for more information.
-:::
-
 ## Versioning
 
 Every destination type is versioned. It is recommended to specify a version for