MicProtocol / docs /third-party-integrations.md
Benaah's picture
Upload folder using huggingface_hub
b17baae verified
|
Raw History Blame Contribute Delete
7.09 kB
# 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`.