Event Webhook Dispatcher

[allenporter]

Add outbound Webhook dispatch system sending HTTP POST notifications to n8n, Home Assistant, Slack, or Discord on sync completion.

[allenporter]

Detailed Technical Implementation Plan

1. User Journeys & Example Use Cases

• Journey A: Home Assistant & Automation Integration
  • Scenario: User wants their home automation platform (Home Assistant / n8n / Zapier) to react when notes finish syncing.
  • Workflow:
    1. User syncs E-ink device before going to bed.
    2. Supernote server dispatches an automated HTTP POST webhook payload to https://n8n.homelab.local/webhook/supernote.
    3. n8n triggers Home Assistant to dim office lights and update a daily tracking dashboard.
  • Outcome: Real-time event notifications enable external workflows without polling.

---

2. Requirements & Technical Specifications

A. Configuration (config.yaml)

webhooks:
  enabled: true
  endpoints:
    - url: "https://n8n.homelab.local/webhook/supernote"
      secret: "hmac-secret-key"
      events:
        - "note.sync_completed"
        - "task.created"

B. Dispatcher Engine (supernote/server/services/webhook.py)

• Listen to internal events in events.py (note.sync_completed, task.created).
• Compute HMAC SHA256 signature in X-Supernote-Signature header for payload integrity.
• JSON Payload Format:

  {
    "event": "note.sync_completed",
    "timestamp": 1785653500,
    "user_id": 1,
    "file": {
      "path": "Note/Daily/2026-08-02.note",
      "page_count": 3
    },
    "processing": {
      "tasks_extracted": 2,
      "summary": "Sprint planning notes..."
    }
  }

• Async non-blocking dispatch using aiohttp.ClientSession with retry backoff.

---

3. Verification & Testing Plan

• Automated Unit Tests (tests/server/test_webhook.py):
  • Test event listener subscription and payload formatting.
  • Verify HMAC SHA256 signature calculation.
  • Test retry behavior on HTTP error status codes.