signalk-webhook-bridge 2.0.0

package/README.md

@@ -0,0 +1,358 @@
+# Webhook Bridge
+
+Webhook Bridge is a Signal K server plugin for sending selected vessel data to an external HTTP webhook at a configurable interval.
+
+Choose the Signal K data paths you want to send, assign simple field names, select your preferred output units, and Webhook Bridge will deliver them as a JSON payload to your endpoint.
+
+If the webhook is unavailable, data is stored locally in a persistent queue and automatically delivered in order when the connection returns.
+
+## Features
+
+- Send selected Signal K data to any HTTP webhook
+- Choose from Signal K paths currently available on the server
+- Assign custom field names for the outgoing payload
+- Convert supported values into useful output units
+- Configurable delivery interval
+- Optional Bearer token authentication
+- Persistent offline queue using SQLite
+- FIFO delivery preserves the original order of queued updates
+- Queued data survives Signal K and system restarts
+- Automatic retry when the webhook becomes available again
+- Manual **Retry Now** control
+- Live delivery and queue status in the plugin configuration screen
+- Values are sent at their available precision without artificial rounding
+
+## How it works
+
+Webhook Bridge periodically takes a snapshot of the Signal K paths you have configured.
+
+The snapshot is written to the local queue **before** delivery is attempted. This means the data is safely queued even if the network connection or receiving server is unavailable at the time of capture.
+
+Webhook Bridge then attempts to deliver the oldest queued entry first.
+
+An entry is removed from the queue only after the receiving webhook returns a successful HTTP response. If delivery fails, the entry remains in the queue and later entries wait behind it, preserving chronological order.
+
+When connectivity returns, the backlog is automatically delivered oldest first.
+
+## Configuration
+
+Open **Server → Plugin Config → Webhook Bridge** in the Signal K administration interface.
+
+### Webhook URL
+
+Enter the HTTP or HTTPS endpoint that should receive the data.
+
+For example:
+
+```text
+https://example.com/api/vessel-data
+```
+
+### Authentication Key
+
+An optional authentication key can be supplied.
+
+When configured, Webhook Bridge sends it using the HTTP `Authorization` header as a Bearer token:
+
+```text
+Authorization: Bearer YOUR_KEY
+```
+
+### Send Interval
+
+Sets the interval, in minutes, between data snapshots.
+
+Each snapshot is stored in the local queue before Webhook Bridge attempts to send it.
+
+### Signal K Data Paths
+
+Add the Signal K values that you want to include in each webhook update.
+
+For each path you can configure:
+
+**Signal K Path**  
+The source value in Signal K, for example:
+
+```text
+navigation.speedOverGround
+```
+
+**Webhook Field Name**  
+The name that will be used for the value in the outgoing JSON, for example:
+
+```text
+speed
+```
+
+**Output Units**  
+Where supported, the Signal K value can be converted before transmission.
+
+The available conversion options depend on the native units of the selected Signal K path.
+
+## Supported unit conversions
+
+Webhook Bridge currently recognises the following native Signal K units:
+
+| Native unit | Available output |
+| --- | --- |
+| `m/s` | Native, knots, km/h, mph |
+| `rad` | Native, degrees |
+| `m` | Native, metres, feet |
+| `K` | Native, Celsius, Fahrenheit |
+| `Pa` | Native, hPa, mbar |
+
+Paths using other units can still be sent using their native value.
+
+Webhook Bridge does not deliberately round converted values. This allows the receiving application to decide how much precision it requires.
+
+## Payload Format
+
+Webhook Bridge sends data to the configured URL as an HTTP `POST` request with a JSON body.
+
+Each Signal K path configured in the plugin becomes a top-level field in the JSON object. The field name is taken from the **Webhook Field Name** entered in the plugin configuration.
+
+For example, if the following paths are configured:
+
+| Signal K Path | Webhook Field Name | Output Units |
+| --- | --- | --- |
+| `navigation.speedOverGround` | `speed` | Knots |
+| `environment.depth.belowTransducer` | `depth` | Native |
+
+the webhook may receive:
+
+```json
+{
+  "timestamp": "2026-09-13T10:15:00.000Z",
+  "speed": 5.649988373552611,
+  "depth": 12.8,
+  "units": {
+    "speed": "kn",
+    "depth": "m"
+  }
+}
+```
+
+### Timestamp
+
+Every request contains a `timestamp` field in ISO 8601 UTC format:
+
+```json
+"timestamp": "2026-09-13T10:15:00.000Z"
+```
+
+This is the time the snapshot was **captured and added to the local queue**, not necessarily the time it was delivered.
+
+This distinction is important when a webhook has been unavailable. Queued updates retain their original capture timestamps when they are subsequently delivered.
+
+### Values
+
+Values are sent as JSON values rather than Signal K value objects.
+
+For example:
+
+```json
+"speed": 5.649988373552611
+```
+
+rather than:
+
+```json
+"speed": {
+  "value": 5.649988373552611
+}
+```
+
+Webhook Bridge does **not round numeric values**. Converted values are sent at the precision produced by the conversion.
+
+### Units
+
+Every payload contains a `units` object identifying the units used for each configured field:
+
+```json
+"units": {
+  "speed": "kn",
+  "depth": "m"
+}
+```
+
+If **Native** is selected, the unit reported by Signal K metadata is used.
+
+If another output unit is selected, Webhook Bridge converts the value before sending it and reports the selected output unit.
+
+Common output labels include:
+
+| Output unit | Payload label |
+| --- | --- |
+| Knots | `kn` |
+| Kilometres per hour | `km/h` |
+| Miles per hour | `mph` |
+| Metres | `m` |
+| Feet | `ft` |
+| Degrees | `deg` |
+| Celsius | `degC` |
+| Fahrenheit | `degF` |
+| Hectopascals | `hPa` |
+| Millibars | `mbar` |
+
+### Authentication
+
+If an **Authentication Key** is configured, Webhook Bridge sends it as a Bearer token in the HTTP `Authorization` header:
+
+```http
+Authorization: Bearer your-authentication-key
+```
+
+If no Authentication Key is configured, the `Authorization` header is omitted.
+
+The request body is sent as JSON with:
+
+```http
+Content-Type: application/json
+```
+
+### Successful Delivery
+
+Your webhook should return an HTTP **2xx status code** when the payload has been successfully received and accepted.
+
+Only after a successful response is the corresponding update removed from Webhook Bridge's local queue.
+
+### Failed Delivery
+
+If the webhook cannot be reached, returns an unsuccessful HTTP response, or another delivery error occurs, the queued update is **not deleted**.
+
+Webhook Bridge retains it locally and attempts delivery again later.
+
+Queued updates are delivered in **FIFO order (oldest first)**. This means that after an outage, the receiving system may receive several requests in succession as Webhook Bridge works through the backlog.
+
+Each request retains its original capture `timestamp`, allowing the receiving system to determine when the data was recorded rather than when it eventually arrived.
+
+### Receiving the Webhook
+
+The receiving application only needs to:
+
+1. Accept HTTP `POST` requests at the configured URL.
+2. Parse the request body as JSON.
+3. Optionally validate the Bearer token if authentication is configured.
+4. Process or store the supplied values.
+5. Return a `2xx` HTTP response only when the payload has been successfully accepted.
+
+Because field names are user-configurable, receiving applications should not assume particular names such as `speed` or `depth`. They should be written to handle the field names configured for that Webhook Bridge installation.
+
+## Offline operation and queueing
+
+Webhook Bridge is designed for installations where internet connectivity may be intermittent.
+
+This is particularly useful aboard vessels where Signal K may continue collecting data while the connection to a shore-based server is unavailable.
+
+Every snapshot is written to a persistent SQLite queue before transmission is attempted.
+
+If delivery fails:
+
+1. The snapshot remains in the queue.
+2. New snapshots continue to be added at the configured interval.
+3. Webhook Bridge periodically attempts delivery again.
+4. When the webhook becomes available, queued entries are delivered oldest first.
+5. An entry is deleted only after successful delivery.
+
+The queue is persistent, so queued entries are retained if Signal K or the host system is restarted.
+
+There is intentionally no configurable queue-size limit. The practical limit is the storage available on the host system.
+
+## Status
+
+The configuration screen provides live information about the webhook connection and local queue, including:
+
+- Current delivery state
+- Number of entries waiting
+- Last data capture
+- Last successful delivery
+- Last delivery error, when applicable
+
+The status display updates automatically.
+
+The **Retry Now** button can be used to immediately attempt delivery of the existing queue. It does **not** create an additional data snapshot.
+
+## HTTP responses
+
+Webhook Bridge considers a request successfully delivered when the receiving server returns a successful HTTP response.
+
+If the receiving server returns an error response, or the request cannot be completed, the queued entry is retained for another attempt.
+
+Receivers should therefore return a successful HTTP status only once they have accepted the payload.
+
+## Requirements
+
+- Signal K Server
+- Node.js 22.5 or later
+
+Node.js 22.5+ is required because Webhook Bridge uses the built-in `node:sqlite` module for persistent queue storage.
+
+## Installation
+
+Install **Webhook Bridge** through the Signal K AppStore.
+
+After installation:
+
+1. Enable the plugin.
+2. Open its configuration page.
+3. Enter your webhook URL.
+4. Add the Signal K paths you want to send.
+5. Choose field names and output units.
+6. Set the required send interval.
+7. Save the configuration.
+
+The status panel can then be used to confirm that data is being captured and delivered.
+
+## Development
+
+Clone the repository and install the dependencies:
+
+```bash
+npm install
+```
+
+Build the configuration interface:
+
+```bash
+npm run build
+```
+
+Run the automated tests:
+
+```bash
+npm test
+```
+
+Before publishing a release, it is also recommended to run:
+
+```bash
+npm audit
+npm pack --dry-run
+```
+
+The built configuration interface is included with the published package; the plugin does not rely on an install-time build step.
+
+## Data storage
+
+The persistent webhook queue is stored within the plugin's Signal K data directory using `app.getDataDirPath()`.
+
+Webhook Bridge does not require a separate database server.
+
+Authentication keys are configuration values and are not included in webhook status responses.
+
+## Licence
+
+Copyright © 2026 Matt Barraud.
+
+Webhook Bridge is free software licensed under the GNU General Public License v3.0 or later. See [LICENSE](LICENSE) for details.
+
+## Author
+
+Developed by Matt Barraud.
+
+## Source
+
+Source code, issues and releases:
+
+[github.com/50North4West/signalk-webhook-bridge](https://github.com/50North4West/signalk-webhook-bridge)
+

package/package.json

@@ -0,0 +1,63 @@
+{
+	"name": "signalk-webhook-bridge",
+	"version": "2.0.0",
+	"description": "Send selected Signal K data paths to an external webhook with unit conversion, persistent queueing and automatic retry.",
+	"main": "plugin/index.js",
+	"scripts": {
+		"build": "webpack --mode production",
+		"dev": "webpack --mode development --watch",
+		"test": "node --test",
+		"prepublishOnly": "npm run build && npm test"
+	},
+	"keywords": [
+		"signalk-node-server-plugin",
+		"signalk-plugin-configurator",
+		"signalk-category-utility",
+		"signalk",
+		"webhook"
+	],
+	"signalk-plugin-enabled-by-default": false,
+	"engines": {
+		"node": ">=22.5.0"
+	},
+	"signalk": {
+		"displayName": "Webhook Bridge",
+		"appIcon": "./assets/icon-128.png",
+		"screenshots": [
+			"./docs/screenshots/config.png"
+		]
+	},
+	"author": "Matt Barraud",
+	"license": "GPL-3.0-or-later",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/50North4West/signalk-webhook-bridge.git"
+	},
+	"homepage": "https://github.com/50North4West/signalk-webhook-bridge#readme",
+	"bugs": {
+		"url": "https://github.com/50North4West/signalk-webhook-bridge/issues"
+	},
+	"files": [
+		"plugin/",
+		"public/",
+		"assets/",
+		"docs/screenshots/",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
+	"dependencies": {
+		"@signalk/server-admin-ui-dependencies": "^2.23.0",
+		"node-fetch": "^2.6.1",
+		"react": "^19.3.0",
+		"react-dom": "^19.3.0"
+	},
+	"devDependencies": {
+		"@babel/core": "^7.29.7",
+		"@babel/preset-env": "^7.29.7",
+		"@babel/preset-react": "^7.29.7",
+		"babel-loader": "^9.2.1",
+		"webpack": "^5.110.3",
+		"webpack-cli": "^7.2.3"
+	}
+}