Hugging Face's logo

Spaces:
Benaah
/
MicProtocol
Running

App Files Community
MicProtocol / docs /third-party-integrations.md
Benaah's picture
Benaah
Upload folder using huggingface_hub
b17baae verified
preview code
|
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.

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 with automatic Clerk user ID binding (formbricks.setUserId(userId)) and route change tracking.
  • API Service Client: listSurveys, getSurveyResponses, createSurvey in SelfHostedClientsService.
  • 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.