Move Webhooks and Custom Content sections to dedicated docs

2026-07-06 01:41:27 +02:00 · 2026-04-17 22:38:15 +01:00
parent ccadfa73fd
commit f1dc155a0f
6 changed files with 209 additions and 136 deletions
@@ -0,0 +1,74 @@
+# Webhooks
+
+The collector can forward certain events to external HTTP endpoints. This is useful for integrating MeshCore Hub with external systems, notification services, or custom processing pipelines.
+
+## Configuration
+
+| Variable                         | Default  | Description                              |
+| -------------------------------- | -------- | ---------------------------------------- |
+| `WEBHOOK_ADVERTISEMENT_URL`      | _(none)_ | Webhook URL for advertisement events     |
+| `WEBHOOK_ADVERTISEMENT_SECRET`   | _(none)_ | Secret sent as `X-Webhook-Secret` header |
+| `WEBHOOK_MESSAGE_URL`            | _(none)_ | Webhook URL for all message events       |
+| `WEBHOOK_MESSAGE_SECRET`         | _(none)_ | Secret for message webhook               |
+| `WEBHOOK_CHANNEL_MESSAGE_URL`    | _(none)_ | Override URL for channel messages only   |
+| `WEBHOOK_CHANNEL_MESSAGE_SECRET` | _(none)_ | Secret for channel message webhook       |
+| `WEBHOOK_DIRECT_MESSAGE_URL`     | _(none)_ | Override URL for direct messages only    |
+| `WEBHOOK_DIRECT_MESSAGE_SECRET`  | _(none)_ | Secret for direct message webhook        |
+| `WEBHOOK_TIMEOUT`                | `10.0`   | Request timeout in seconds               |
+| `WEBHOOK_MAX_RETRIES`            | `3`      | Max retry attempts on failure            |
+| `WEBHOOK_RETRY_BACKOFF`          | `2.0`    | Exponential backoff multiplier           |
+
+### URL Routing
+
+- `WEBHOOK_MESSAGE_URL` receives **both** channel and direct message events unless overridden.
+- `WEBHOOK_CHANNEL_MESSAGE_URL` overrides the URL for channel messages only.
+- `WEBHOOK_DIRECT_MESSAGE_URL` overrides the URL for direct messages only.
+
+### Secrets
+
+Each webhook URL can optionally have a corresponding secret. When configured, the secret is sent as the `X-Webhook-Secret` HTTP header, allowing the receiving endpoint to verify the request origin.
+
+### Retries
+
+Failed webhook deliveries are retried with exponential backoff:
+
+- **`WEBHOOK_MAX_RETRIES`** — Maximum number of retry attempts (default: 3).
+- **`WEBHOOK_RETRY_BACKOFF`** — Backoff multiplier applied between retries (default: 2.0). For example, with the default settings, retries occur at approximately 2s, 4s, and 8s.
+
+## Payload Format
+
+All webhooks send a JSON POST request with the following structure:
+
+```json
+{
+  "event_type": "advertisement",
+  "public_key": "abc123...",
+  "payload": { ... }
+}
+```
+
+### Event Types
+
+| Event Type        | Trigger                          | Payload Content              |
+| ----------------- | -------------------------------- | ---------------------------- |
+| `advertisement`   | Node advertisement received      | Advertisement event data     |
+| `channel_message` | Channel message received         | Channel message event data   |
+| `direct_message`  | Direct message received          | Direct message event data    |
+
+### Example: Advertisement Webhook
+
+```bash
+# .env
+WEBHOOK_ADVERTISEMENT_URL=https://example.com/webhook
+WEBHOOK_ADVERTISEMENT_SECRET=my-secret-key
+```
+
+### Example: Separate Channel and Direct Message Webhooks
+
+```bash
+# .env
+WEBHOOK_CHANNEL_MESSAGE_URL=https://example.com/channel-webhook
+WEBHOOK_CHANNEL_MESSAGE_SECRET=channel-secret
+WEBHOOK_DIRECT_MESSAGE_URL=https://example.com/direct-webhook
+WEBHOOK_DIRECT_MESSAGE_SECRET=direct-secret
+```