Webhook Forwarding & Batching
Relevant source files
The following files were used as context for generating this wiki page:
- app/src/main/kotlin/com/fathiraz/flowbell/domain/usecases/SendWebhookUseCase.kt
- app/src/main/kotlin/com/fathiraz/flowbell/data/services/WebhookService.kt
- app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt
- app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt
- app/src/main/kotlin/com/fathiraz/flowbell/data/remote/dto/WebhookPayload.kt
- app/src/main/kotlin/com/fathiraz/flowbell/domain/entities/Webhook.kt
- app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/webhook/WebhookViewModel.kt
Webhook Forwarding & Batching is the core data egress system of FlowBell. It is responsible for capturing Android system notifications, transforming them into a standardized JSON format, and transmitting them to user-defined HTTPS endpoints. The system is designed to handle notification bursts efficiently by utilizing a batching mechanism that groups outgoing requests to optimize device performance and network usage.
Sources: README.md:16-19, app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:89-92
Architecture and Data Flow
The system operates as a pipeline starting from the NotificationListenerService, which intercepts system-level alerts. These alerts are filtered and added to a ConcurrentLinkedQueue for asynchronous processing. A specialized WebhookService handles the mapping of raw notification data into a WebhookPayload, which includes device metadata, application info, and security nonces.
High-Level Data Flow
The following diagram illustrates the lifecycle of a notification from capture to webhook delivery.
The flow ensures that only notifications from allowed apps that pass keyword filters are queued for delivery.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:133-166, app/src/main/kotlin/com/fathiraz/flowbell/data/services/WebhookService.kt:32-44
Batch Processing Logic
To prevent overwhelming the device or the target server during notification bursts, FlowBell employs a batching strategy. Notifications are collected in a thread-safe queue and processed at a fixed interval.
- Cadence: The system attempts to process the batch every 5 seconds.
- Queue Management: A
ConcurrentLinkedQueueis used to holdNotificationDataobjects until the next processing cycle. - Execution: A Coroutine-driven loop in
NotificationListenerServicemanages the timing and triggers theprocessBatch()function.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:92-111, README.md:95-96
Webhook Payload Structure
The WebhookPayload is a standardized data transfer object (DTO) used for all outgoing requests. It ensures that the receiving endpoint receives consistent metadata regarding the device and the notification source.
| Component | Description | Fields |
|---|---|---|
| AppInfo | Details about the source application | packageName, name, version |
| Notification | The content of the alert | title, text, priority, isOngoing |
| Device | Metadata about the sender | id, platform, model, manufacturer |
| Security | Verification metadata | signature, nonce, algorithm |
Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/remote/dto/WebhookPayload.kt:11-37, README.md:144-184
Implementation Details
Security and Validation
The system strictly enforces HTTPS for all webhook URLs to ensure data in transit remains encrypted. Additionally, WebhookService includes hooks for HMAC-SHA256 signing, allowing the receiving server to verify the authenticity of the payload.
Network Handling
HttpRequestUtils manages the low-level OkHttp client. It includes logic for:
- DNS Resolution Check: Validating the hostname before attempting the request to provide better error messages.
- Connectivity Validation: Checking if the device has an active internet connection (
NET_CAPABILITY_INTERNET). - Timeouts: Configured with a 30-second connect timeout and 45-second read timeout.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:26-38, app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:53-76
Testing Mechanism
Users can validate their endpoints using a built-in tester in the WebhookViewModel. This sends a standard test payload (UUID java.util.UUID.randomUUID()) to the configured URL without saving it to preferences until a successful response (HTTP 200-299) is received.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/webhook/WebhookViewModel.kt:133-162, app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:127-160
Conclusion
The Webhook Forwarding & Batching system provides a robust bridge between Android notifications and external automation tools. By combining a 5-second batching cadence with structured JSON payloads and HTTPS enforcement, FlowBell ensures reliable and secure notification delivery while minimizing impact on device battery and performance.