Feature Request: Webhooks for Event-Driven Notifications

[NewtTheWolf]

Summary:
Adding support for webhooks in Latitude, enabling real-time notifications for project changes. Users could subscribe to specific events (e.g., project creation, document version updates, or deletion) and receive authenticated notifications via webhooks.

Request Details:

1. Configurable Webhook Subscriptions
   Users should be able to select and subscribe to specific events, such as:

   • Project creation (Create Project)
   • Folder creation (Create Folder)
   • Document creation (Create Document)
   • New version creation (Create New Version)
   • Document deletion (Delete Document)
   • And other relevant events in the platform's ecosystem

2. Authentication & Verification
   To ensure secure communication, initial webhook setup could follow a verification protocol similar to Facebook’s method:

   • Verification Request: When a user configures a webhook URL and provides a secret token, Latitude would send a GET request to the URL, including parameters like hub.mode=subscribe, hub.verify_token=<provided_token>, and hub.challenge=<random_int>.
   • Validation: Upon receiving the GET request, the endpoint would validate that hub.verify_token matches the user-provided secret. It would then respond with the hub.challenge value, confirming the endpoint's authenticity.

3. Event Notification Signing
   Each event notification payload sent to the webhook would be signed using a method such as SHA256, with the signature in the header (e.g., X-Hub-Signature-256). This would enable endpoint servers to verify the payload’s authenticity. The verification process would involve:

   • Generating a SHA256 hash using the payload and the user-defined secret.
   • Comparing the generated hash with the X-Hub-Signature-256 header to confirm that the payload is genuine.

4. Reliable Delivery with Retry Mechanism
   Implement a retry mechanism to handle cases where webhook delivery fails. After repeated failures, users would be notified to check their webhook endpoint, and re-subscription may be required if the endpoint remains unreachable.

5. Example Payload Structures
   The following examples illustrate how event payloads could be structured to provide relevant data in a consistent format:

   • Project Created Event:

     {
       "event": "project.created",
       "timestamp": "2024-11-09T14:33:22Z",
       "data": {
         "projectId": "12345",
         "projectName": "New AI Project",
         "createdBy": "user@example.com"
       }
     }

   • New Version Created Event:

     {
       "event": "version.created",
       "timestamp": "2024-11-09T15:12:10Z",
       "data": {
         "projectId": "12345",
         "versionId": "some-uuid",
         "version": "v1.0.2",
         "createdBy": "user@example.com",
         "notes": "Bug fixes and improvements"
       }
     }

   • Document Created Event:

     {
       "event": "document.created",
       "timestamp": "2024-11-09T16:45:30Z",
       "data": {
         "projectId": "12345",
         "versionId": "some-uuid",
         "documentId": "some-uuid",
         "documentPath": "path/to/document",
         "createdBy": "user@example.com"
       }
     }

   • Document Deleted Event:

     {
       "event": "document.deleted",
       "timestamp": "2024-11-09T17:25:10Z",
       "data": {
         "projectId": "12345",
         "versionId": "some-uuid",
         "documentId": "some-uuid",
         "deletedBy": "user@example.com"
       }
     }

6. Secure and Flexible Implementation
   Each event payload should be structured in JSON format, containing:

   • event: The type of event that triggered the webhook.
   • timestamp: ISO 8601 formatted timestamp for when the event occurred.
   • data: Object holding event-specific details, such as projectId, versionId, documentId, documentPath, and the initiating user’s email or ID.

---

This feature would enhance Latitude's flexibility and integration capabilities by allowing seamless, secure notifications for critical events.