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:

{
  "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

# .env
WEBHOOK_ADVERTISEMENT_URL=https://example.com/webhook
WEBHOOK_ADVERTISEMENT_SECRET=my-secret-key

Example: Separate Channel and Direct Message Webhooks

# .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

3.2 KiB Raw Blame History