What you can do#
The custom webhook integration lets you connect LumenFlow to any external system that can send or receive HTTP requests. Unlike the built-in channel integrations (Slack, Teams, Discord), custom webhooks give you full control over the payload format and authentication.
| Action | Description | Status |
|---|---|---|
| Send outbound | POST/PUT/PATCH to any external URL | Shipped |
| Receive inbound | Accept signed webhook events from external systems | Shipped |
| Custom body template | Define the outbound payload structure | Shipped |
| Flexible field mapping | Map inbound fields for event id, channel, timestamp | Shipped |
| Approval routing | Route outbound calls through approval workflow | Shipped |
Setup#
- Go to Settings > Connections in LumenFlow
- Click Add Connection > Custom Webhook
- Enter the required fields:
- Outbound URL -- where LumenFlow sends events
- Shared Secret -- used for HMAC signature verification
- Optionally configure:
- Default channel -- fallback channel name for routing
- Outbound HTTP method -- POST (default), PUT, or PATCH
- Auth header name -- custom authorization header
- Body template -- custom JSON template for outbound payloads
- Click Save
Inbound webhook#
After saving, LumenFlow generates a unique inbound endpoint:
https://your-domain.com/api/v1/sidekick/integrations/webhook?key=<unique-key>
External systems POST JSON to this URL. LumenFlow verifies the HMAC signature and ingests the event into Sidekick's channel inbox.
Required headers#
| Header | Description |
|---|---|
x-sidekick-signature | HMAC-SHA256 signature of the request body |
x-sidekick-timestamp | ISO 8601 timestamp for replay protection |
Inbound payload fields#
LumenFlow extracts event data from these JSON fields (configurable):
| Field | Default key | Description |
|---|---|---|
| Event ID | event_id | Unique event identifier (falls back to SHA-256 hash) |
| Channel | channel | Routing channel (falls back to default channel) |
| Message ID | message_id | External message identifier |
| Timestamp | event_ts | Event timestamp (ISO 8601 or Unix epoch) |
| User text | text, message, content, or body | Message content for chat processing |
Security#
- HMAC signature verification -- every inbound request is verified against the shared secret using SHA-256
- Timestamp replay protection -- stale timestamps are rejected
- URL safety validation -- outbound URLs are checked against SSRF protections before saving
- Rate limiting -- distributed per-integration and per-workspace limits
- Credentials encrypted at rest -- the shared secret is encrypted before storage
Use cases#
- CRM notifications -- receive deal updates from your CRM
- Alerting -- push alerts to an internal dashboard or tool
- Custom bots -- wire up any chat system not natively supported
- CI/CD -- receive build and deploy notifications
info Custom webhooks support bidirectional communication. Use outbound webhooks to push data to external systems, and the inbound endpoint to receive events back. Both directions are governed by your workspace's approval rules.