Spaces:
Sleeping
Sleeping
|
Download docs/third-party-integrations.md from Benaah/MicProtocol: direct link, hf CLI and curl.
- Browser
- Download file 7.09 kB
-
https://huggingface.co/spaces/Benaah/MicProtocol/resolve/main/docs/third-party-integrations.md
- Command line
-
hf download hf://spaces/Benaah/MicProtocol/docs/third-party-integrations.md
-
curl -L -o third-party-integrations.md https://huggingface.co/spaces/Benaah/MicProtocol/resolve/main/docs/third-party-integrations.md
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`. | |