# MicProtocol – Third-Party & Self-Hosted Integrations Guide

## Overview

MicProtocol features an extensive suite of self-hosted, open-source integration services alongside external cloud provider APIs. This architecture provides maximum data ownership, cost predictability, and zero-vendor-lockin deployment options.

```mermaid
graph TD
    API[MicProtocol NestJS API :4000] -->|x-api-key| Formbricks[Formbricks :3001]
    API -->|Bearer Token| CalCom[Cal.com :3002]
    API -->|api_access_token| Chatwoot[Chatwoot :3005]
    API -->|Bearer Token| Documenso[Documenso :3004]
    API -->|Basic Auth| Listmonk[Listmonk :9000]
    API -->|JWT Webhook| LiveKit[LiveKit SFU :7880]
    API -->|S3 Client| MinIO[MinIO / R2 :9001]

    Formbricks -->|x-formbricks-signature| WebhookCtrl[IntegrationsWebhookController]
    CalCom -->|x-cal-secret-key| WebhookCtrl
    Chatwoot -->|x-chatwoot-signature| WebhookCtrl
    Documenso -->|x-documenso-signature| WebhookCtrl
    Listmonk -->|x-listmonk-secret| WebhookCtrl
    LiveKit -->|Authorization| WebhookCtrl
```

---

## 1. Self-Hosted Integrations Directory

### 📋 Formbricks (Surveys & Guest Feedback)
* **Purpose**: Collect post-interview feedback, technical profiles, and survey responses from podcast guests and listeners.
* **Architecture**: v4 stack composed of Formbricks Web App (`:3001`), Hub API (`:8080`), Cube Analytics (`:4000`), Database Migrator, and S3 Storage.
* **Frontend Web SDK**: `@formbricks/js` initialized in [`FormbricksProvider.tsx`](file:///home/homel/Desktop/MicProtocol/apps/web/src/components/FormbricksProvider.tsx) with automatic Clerk user ID binding (`formbricks.setUserId(userId)`) and route change tracking.
* **API Service Client**: `listSurveys`, `getSurveyResponses`, `createSurvey` in [`SelfHostedClientsService`](file:///home/homel/Desktop/MicProtocol/apps/api/src/integrations/clients/self-hosted-clients.service.ts).
* **Webhook Endpoint**: `POST /api/integrations/webhooks/formbricks`
  * **Header**: `x-formbricks-signature`
  * **Security**: HMAC constant-time signature verification (`crypto.timingSafeEqual`).
  * **Side Effects**: Automatically logs survey completion events (`follow_up`) in `GuestJourneyEvent`.

---

### 🗓️ Cal.com (Scheduling & Calendar Synchronization)
* **Purpose**: Provide self-hosted meeting and booking scheduling for podcast interviews.
* **Port**: `:3002` (Container: `micprotocol-calcom`).
* **API Service Client**: `listEventTypes`, `createBooking` in `SelfHostedClientsService`.
* **Webhook Endpoint**: `POST /api/integrations/webhooks/calcom`
  * **Header**: `x-cal-secret-key`
  * **Security**: Verified against `CALCOM_WEBHOOK_SECRET` using timing-safe comparison.
  * **Side Effects**: Syncs booking state changes (`isConfirmed`) directly to Prisma `Booking` records.

---

### 💬 Chatwoot (Customer Support & Guest Inbox)
* **Purpose**: Omnichannel guest messaging, host support, and live chat widget.
* **Port**: `:3005` (Container: `micprotocol-chatwoot-web`).
* **API Service Client**: `createChatwootConversation`, `sendChatwootMessage`, `createChatwootContact`.
* **Account Resolution**: Supports dynamic workspace account ID lookups via `chatwootAccountId(accountId)`.
* **Webhook Endpoint**: `POST /api/integrations/webhooks/chatwoot/:accountId`
  * **Header**: `x-chatwoot-signature`
  * **Security**: Verified against `CHATWOOT_WEBHOOK_SECRET`.

---

### ✍️ Documenso (Document E-Signatures)
* **Purpose**: Manage guest appearance releases, NDA agreements, and podcast contracts.
* **Port**: `:3004` (Container: `micprotocol-documenso`).
* **API Service Client**: `sendDocument`, `getDocumentStatus` in `SelfHostedClientsService`.
* **Prerequisites**: Requires PKCS#12 signing certificate mounted at `./scripts/documenso-cert/cert.p12`.
* **Webhook Endpoint**: `POST /api/integrations/webhooks/documenso`
  * **Header**: `x-documenso-signature`
  * **Security**: Verified against `DOCUMENSO_WEBHOOK_SECRET`.

---

### 📰 Listmonk (Email Newsletters & Campaigns)
* **Purpose**: Mass email marketing, subscriber list management, and transactional email distribution.
* **Port**: `:9000` (Container: `micprotocol-listmonk`).
* **API Service Client**: `listLists`, `createList`, `subscribe`, `sendTransactional` via Basic Auth.
* **Webhook Endpoint**: `POST /api/integrations/webhooks/listmonk`
  * **Header**: `x-listmonk-secret`
  * **Security**: Verified against `LISTMONK_WEBHOOK_SECRET`.

---

### 🎙️ LiveKit (WebRTC Multi-Participant SFU Studio)
* **Purpose**: Real-time high-fidelity multi-track audio/video recording studio.
* **Port**: `:7880` (Container: `micprotocol-livekit`).
* **Webhook Endpoint**: `POST /api/integrations/webhooks/livekit`
  * **Header**: `Authorization` JWT (HS256, `iss` = `LIVEKIT_API_KEY`, signed with `LIVEKIT_API_SECRET`)
  * **Security**: JWT signature + issuer/expiry verification **plus** the JWT's `sha256` body claim verified over the raw request body (matches `livekit-server-sdk`'s `WebhookReceiver`). This is LiveKit's only documented webhook auth — a duplicate Svix-style controller that registered the same route was removed.
  * **Room naming**: rooms are created as `episode-{episodeId}` (see `LivekitService.roomName`) and parsed back on webhook receipt.
  * **Side Effects**: `room_finished` → `RecordingSession` status `completed`; `egress_ended` (server-side recording/egress) → status `processing`.

---

### 📊 Umami & Storage (MinIO / Cloudflare R2)
* **Umami Analytics**: `:3003` self-hosted web analytics tracking dashboard pageviews and conversion events.
* **MinIO S3 Storage**: `:9001` (Console `:9090`). Automatically initializes S3 buckets (`micprotocol-storage`, `calcom-uploads`, `documenso-uploads`, `formbricks-uploads`). In production, supports seamless migration to Cloudflare R2 without code changes.

---

## 2. Backend Request & Latency Tracing System

MicProtocol incorporates a global NestJS Tracing system for APM and diagnostics:

* **Header Propagation**:
  * Response header `X-Trace-Id`: Unique identifier (`tr-xxxxxxxx`) passed across microservices and clients.
  * Response header `X-Response-Time`: High-resolution execution duration in milliseconds (`X-Response-Time: 18ms`).
* **Telemetry Endpoints**:
  * `GET /tracing/spans`: Returns recent execution spans and p95 latency.
  * `GET /tracing/metrics`: Returns total request count, average latency, and error rate percentages.
* **Admin Visualizer**: Accessible via Admin Dashboard at `/monitoring` and `/analytics`.

---

## 3. Webhook Security Checklist

1. **HMAC Timing-Safe Verification**: All webhook endpoints utilize `crypto.timingSafeEqual()` to prevent timing side-channel attacks.
2. **Environment Secret Enforcement**: In production, ensure non-default values are generated for `FORMBRICKS_WEBHOOK_SECRET`, `CALCOM_WEBHOOK_SECRET`, `CHATWOOT_WEBHOOK_SECRET`, `DOCUMENSO_WEBHOOK_SECRET`, and `LISTMONK_WEBHOOK_SECRET`. LiveKit webhooks have no shared-secret header — they are authenticated by the `Authorization` JWT verified against `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET`.