Webhook Payload Structure

Relevant source files

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

• app/src/main/kotlin/com/fathiraz/flowbell/data/remote/dto/WebhookPayload.kt
• README.md
• app/src/main/kotlin/com/fathiraz/flowbell/data/mappers/NotificationMapper.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

The Webhook Payload Structure in FlowBell defines the standardized JSON format used to transmit captured Android notifications to external endpoints. This structure ensures that downstream automation tools, such as n8n or custom dashboards, receive consistent metadata regarding the originating application, the notification content, device hardware details, and security verification.

The payload is generated by the NotificationListenerService and WebhookService, which aggregate data from the Android system and map it into a serializable Data Transfer Object (DTO). This process includes enriching the raw notification with device identifiers and generating security nonces to prevent replay attacks.

Sources: README.md:154-159, app/src/main/kotlin/com/fathiraz/flowbell/data/remote/dto/WebhookPayload.kt:1-12

Core Data Models

The payload is structured into several nested objects, each representing a specific domain of the captured event. The primary entry point is the WebhookPayload class, which aggregates app, notification, media, device, and security information.

Payload Schema Overview

Field	Type	Description
id	String	A unique UUID for the specific notification event.
timestamp	String	ISO 8601 formatted string representing when the event occurred.
app	Object	Metadata about the application that posted the notification.
notification	Object	The actual content (title, text) and priority of the alert.
media	Object	URIs or Base64 strings for icons associated with the alert.
device	Object	Hardware and OS version details of the sending Android device.
security	Object	Signature and nonce for verifying payload integrity.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/remote/dto/WebhookPayload.kt:13-33, README.md:162-200

Class Relationship Diagram

The following diagram illustrates the relationship between the various DTO components defined in the data layer.

Payload Generation & Mapping

The transformation from system StatusBarNotification objects to the final JSON payload involves a multi-step mapping process. This is primarily handled by the NotificationMapper and WebhookService.

Data Flow for Payload Creation

The NotificationListenerService captures the notification and utilizes NotificationMapper to populate the WebhookPayload fields.

Detailed Field Mapping Logic

1. Application Metadata: The packageName is retrieved directly from the StatusBarNotification, while the name is resolved using the Android PackageManager.
2. Notification Details: Content is extracted from notification extras (e.g., Notification.EXTRA_TITLE). The priority is converted from Android integer constants (e.g., PRIORITY_HIGH) to string labels (high, normal, low).
3. Device Information: The system uses android.os.Build constants such as FINGERPRINT for the device ID and MANUFACTURER for brand identification.
4. Security: A unique nonce is generated for every payload using UUID.randomUUID() to ensure request uniqueness.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:205-235, app/src/main/kotlin/com/fathiraz/flowbell/data/mappers/NotificationMapper.kt:114-124

Security and Verification

The WebhookPayload includes a SecurityPayload object designed to support payload signing and integrity checks.

• Signature Generation: The WebhookService can generate an HMAC-SHA256 signature by serializing the payload to JSON and signing it with a configured secret key.
• Nonce: Every request includes a unique nonce to prevent replay attacks.
• Algorithm: The default algorithm is set to HMAC-SHA256.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/services/WebhookService.kt:76-108, app/src/main/kotlin/com/fathiraz/flowbell/data/remote/dto/WebhookPayload.kt:93-100

Implementation Example

The HttpRequestUtils class utilizes a hardcoded test payload structure to validate webhook endpoints before they are saved by the user. This ensures the endpoint can handle the standard project format.

// Example of how the payload is constructed in HttpRequestUtils.kt
val testPayload = """
    {
      "id": "${java.util.UUID.randomUUID()}",
      "timestamp": "${java.time.Instant.now()}",
      "app": {
        "packageName": "com.fathiraz.flowbell",
        "name": "FlowBell Test",
        "version": "1.0.0"
      },
      "notification": {
        "title": "FlowBell Webhook Test",
        "text": "This is a test notification from FlowBell webhook system",
        "subText": null,
        "priority": "normal",
        "isOngoing": false,
        "isClearable": true,
        "category": null
      },
      ...
    }
""".trimIndent()

Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:139-165

Conclusion

The Webhook Payload Structure is a robust, nested JSON format that centralizes all necessary information for remote automation. By decoupling the captured notification from the transport layer and using standardized DTOs, FlowBell provides a reliable contract for developers to build third-party integrations.