Webhook Provider

The Webhook provider exposes a local HTTP endpoint that accepts incoming messages via POST requests. It is ideal for integrating with CI/CD pipelines, monitoring tools, home automation platforms, and any system that can make HTTP requests.

Because the server runs directly inside channelBar, there is no external dependency—messages arrive instantly without polling or third-party services.

Endpoint

The webhook server provides two routes:

Method Path Description
POST /message/{channel} Send a message to the specified channel
GET /health Health check – returns {"status": "running", "channels": N}

The default base URL is http://localhost:8080. The port can be changed in Settings.

Request Format

Send messages as JSON with the Content-Type: application/json header.

Field Required Description
text Yes Message content
source No Source label (e.g. the name of the sending system)
link No URL opened when the message is clicked
open No Command or application to execute
message_context No JSON object with arbitrary metadata attached to the message
channel_context No JSON object with channel-level context data

Authentication

Authentication is optional and configured per channel. When an API key is set, every request to that channel must include the key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Requests without a valid key receive an HTTP 401 Unauthorized response.

Server Settings

Configure the webhook server under Settings → Servers → Webhook Server:

Setting Default Description
Port 8080 Listening port (range: 1024–65535)
Enable CORS Off Allow cross-origin requests from browser-based clients
Rate Limit 100 Maximum requests per minute; excess requests receive HTTP 429
Allow External Connections Off When enabled, the server binds to all network interfaces (0.0.0.0) instead of localhost only

Security Warning: Only enable Allow External Connections if you understand the implications. The webhook server has no built-in TLS and is designed for trusted local networks. For internet-accessible messaging, use the channelBar Cloud Service instead.

Configuration

To enable the Webhook provider for a channel:

  1. Open Settings → Channels
  2. Select the target channel
  3. Navigate to the Providers tab
  4. Enable Webhook
  5. Optionally set an API key for authentication

Examples

Simple message

curl -X POST http://localhost:8080/message/work \
  -H "Content-Type: application/json" \
  -d '{"text":"Build successful"}'

With authentication and options

curl -X POST http://localhost:8080/message/work \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "text": "Deploy v2.4.1 completed",
    "source": "GitHub Actions",
    "link": "https://github.com/org/repo/actions/runs/123"
  }'

Health check

curl http://localhost:8080/health

Validation Limits

Field Limit
text 10 KB
source 256 characters
link 2048 characters
open 2048 characters
message_context 10 KB
channel_context 10 KB
Next
MQTT