mirror of
https://github.com/ipnet-mesh/meshcore-hub.git
synced 2026-07-02 07:51:07 +02:00
Louis King
973bf23fe8
Move scattered configuration tables and operational sections out of the README into dedicated reference documents: - docs/configuration.md: single source of truth for all environment variables, grouped into 12 sections (Common, Database, Caching, Collector, Webhooks, Auth, Data Retention, API, Web Dashboard, Feature Flags, Traefik, Prometheus & Alertmanager) - docs/deployment.md: production setup, reverse proxy, multi-instance, API scaling, Redis caching - docs/observer.md: remote observers plus PACKETCAPTURE_* and SERIAL_PORT reference - docs/maintenance.md: backup and restore README is reduced from 712 to 385 lines; the ARM32/Raspberry Pi note is dropped. database.md, auth.md, webhooks.md, and content.md have their env-var tables removed and link back to configuration.md. Stale cross-references in database.md, upgrading.md, and .env.example are updated to point at the new locations.
60 lines
2.3 KiB
Markdown
60 lines
2.3 KiB
Markdown
# 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
|
|
|
|
Webhook behaviour is configured via `WEBHOOK_*` environment variables. For the full variable reference (URLs, secrets, timeout, retries, backoff), see [configuration.md → Webhooks](configuration.md#webhooks). The sections below describe how the configured values behave.
|
|
|
|
### 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 controlled by `WEBHOOK_MAX_RETRIES` (default `3`) and `WEBHOOK_RETRY_BACKOFF` (default `2.0`). With the defaults, 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
|
|
```
|