Usage Guide & Webhook Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt
• app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/webhook/WebhookViewModel.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/webhook/WebhookMainScreen.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/webhook/WebhookEditScreen.kt
• app/src/main/kotlin/com/fathiraz/flowbell/data/remote/dto/WebhookPayload.kt
• app/src/main/kotlin/com/fathiraz/flowbell/data/local/preferences/DataStoreManager.kt

FlowBell is a notification bridge that captures Android system notifications and forwards them to a user-defined HTTPS webhook. This guide details the configuration of the webhook endpoint, the validation mechanisms employed by the application, and the lifecycle of a notification from device capture to remote delivery.

The system relies on a NotificationListenerService to monitor device activity, filtering events based on per-app user preferences and keyword configurations. Once captured, notifications are batched and transmitted as JSON payloads to external services like Zapier, n8n, or custom API endpoints.

Sources: README.md:16-24, app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:252-270

Webhook Configuration and Validation

Users manage webhook settings through the Webhook and Webhook Edit screens. The application enforces security and structural constraints on the URL to ensure reliable delivery.

Configuration Process

The configuration workflow involves entering a URL, performing a DNS and TLS connectivity test, and persisting the setting to on-device storage.

The application performs a series of checks before allowing a URL to be saved to ensure connectivity and protocol security.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/webhook/WebhookEditScreen.kt:111-140, app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:115-125

Validation Requirements

The WebhookViewModel and HttpRequestUtils enforce the following rules:

Requirement	Logic / Implementation	Source
Protocol	Must start with https:// for secure communication.	WebhookViewModel.kt:216
Format	Validated via regex for domain, port, and path structure.	WebhookViewModel.kt:225-234
DNS Resolution	Attempts InetAddress.getByName() and getAllByName() to verify host reachability.	HttpRequestUtils.kt:53-76
HTTP Method	Uses POST (default) or PUT for data transmission.	HttpRequestUtils.kt:182

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/webhook/WebhookViewModel.kt:214-235, app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:50-80

Data Flow: From Notification to Webhook

FlowBell uses a batch processing architecture to minimize battery impact while maintaining near real-time delivery.

Capture and Filtering

1. Detection: NotificationListenerService receives a StatusBarNotification.
2. Deduplication: A cache of the last 100 notification IDs is checked to prevent duplicate triggers.
3. App Filtering: The service queries AppPreferencesRepository to verify if the source application is enabled for forwarding.
4. Keyword Filtering: NotificationFilterUtil checks the title and text against global and per-app keyword filters.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:120-170

Batch Delivery Logic

Captured notifications are added to a ConcurrentLinkedQueue. A background job drains this queue every 5 seconds (default cadence) to perform batch delivery.

The sequence shows how notifications are aggregated before transmission to optimize network usage.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:89-115, app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:272-300

Webhook Payload Structure

The payload is a standardized JSON object containing metadata about the application, the notification content, device state, and security markers.

JSON Schema Elements

Field	Type	Description
id	UUID	Unique identifier for the notification event.
timestamp	ISO 8601	The time the notification was posted.
app.packageName	String	Android package identifier (e.g., com.whatsapp).
notification.text	String	The main body text of the alert.
device.model	String	Hardware model (e.g., Pixel 7).
security.nonce	String	Alphanumeric string for request tracking and security.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/remote/dto/WebhookPayload.kt:13-90

Example Payload

{
  "id": "e27fe565-51b4-48f8-92ef-f4c4d33580c8",
  "timestamp": "2025-09-24T01:28:58.039Z",
  "app": {
    "packageName": "com.fathiraz.flowbell",
    "name": "FlowBell",
    "version": "1.0.0"
  },
  "notification": {
    "title": "Alert",
    "text": "Your notification content here",
    "priority": "normal",
    "isOngoing": false,
    "isClearable": true
  },
  "device": {
    "id": "google/sdk_gphone64_arm64",
    "platform": "android",
    "version": "14"
  },
  "security": {
    "nonce": "8fbd0c9b7f7e4972b5c0d4e2cf33b0ea",
    "algorithm": "HMAC-SHA256"
  }
}

Sources: README.md:155-200, app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:472-510

Persistence and Reliability

Storage Mechanisms

FlowBell uses DataStore for primary configuration and a fallback SharedPreferences system to ensure reliability, particularly for Samsung devices where storage corruption can occur.

The persistence logic includes a secondary write to SharedPreferences to prevent loss of critical endpoint configuration.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/local/preferences/DataStoreManager.kt:111-150

Delivery Monitoring

Users can monitor the status of deliveries through the History tab or the Dashboard.

• Success: HTTP 200-299 status codes.
• Failure: Logs detailed error messages (DNS, Timeout, SSL/TLS errors).
• Retry: The system includes scaffolding for an automatic retry mechanism with exponential backoff.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/webhook/WebhookMainScreen.kt:116-135, app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:145-165

Conclusion

Setting up a webhook in FlowBell transforms an Android device into a programmable notification gateway. By combining robust URL validation, secure batch processing, and a resilient persistence layer, the application ensures that notification data is delivered reliably to any HTTPS-compliant endpoint. Proper configuration involves verifying host resolution and ensuring the receiving server is prepared to handle standardized JSON POST requests.