Blame for docs/webhooks.md

# Webhooks

MicProtocol receives webhooks from six self-hosted integrations and one realtime SFU. Every webhook is verified, idempotent (via `WebhookIdempotencyService`), and side-effect-bearing. This doc is the entire HTTP webhook reference.

For the high-level integration architecture, see [Third-Party & Self-Hosted Integrations](./third-party-integrations.md). For the service-client code that calls these integrations outbound, see [`apps/api/src/integrations/clients/self-hosted-clients.service.ts`](../apps/api/src/integrations/clients/self-hosted-clients.service.ts).

## Security Model

Every webhook handler enforces three guarantees:

1. **HMAC timing-safe signature verification** — uses `crypto.timingSafeEqual()` so attackers cannot infer the secret via response timing.
2. **Idempotent processing** — `WebhookIdempotencyService.generateEventKey()` derives a deterministic key from the payload; duplicate deliveries within the TTL window return `{ received: true, duplicate: true }` and short-circuit side effects.
3. **Workspace-scoped side effects** — every state change writes to a record that ultimately chains back to a `Workspace` via `podcastId`, preserving tenant isolation.

The verification helper lives in [`apps/api/src/integrations/integrations-webhook.controller.ts`](../apps/api/src/integrations/integrations-webhook.controller.ts):

```ts
function timingSafeCompare(provided?: string, expected?: string): boolean {
  if (!provided || !expected) return false;
  const bufProvided = Buffer.from(provided);
  const bufExpected = Buffer.from(expected);
  if (bufProvided.length !== bufExpected.length) return false;
  return crypto.timingSafeEqual(bufProvided, bufExpected);
}
```

If the matching `*_WEBHOOK_SECRET` env var is unset (empty string), verification is **skipped** with a logged warning — useful for first-boot testing but you must set every secret before production.

## Endpoint Catalog

All webhooks are mounted under `POST /integrations/webhooks/<provider>` on the API (`:4000` by default).

| Provider | Endpoint | Auth header | Secret env var | Source |
|---|---|---|---|---|
| Cal.com | `/integrations/webhooks/calcom` | `x-cal-secret-key` | `CALCOM_WEBHOOK_SECRET` | Cal.com Admin → Webhooks |
| Chatwoot | `/integrations/webhooks/chatwoot/:accountId` | `x-chatwoot-signature` | `CHATWOOT_WEBHOOK_SECRET` | Chatwoot Settings → Webhooks |
| Documenso | `/integrations/webhooks/documenso` | `x-documenso-signature` | `DOCUMENSO_WEBHOOK_SECRET` | Documenso Admin → Webhooks |
| Formbricks | `/integrations/webhooks/formbricks` | `x-formbricks-signature` | `FORMBRICKS_WEBHOOK_SECRET` | Formbricks Admin → Webhooks |
| Listmonk | `/integrations/webhooks/listmonk` | `x-listmonk-secret` | `LISTMONK_WEBHOOK_SECRET` | Listmonk Settings → Webhooks |
| LiveKit | `/integrations/webhooks/livekit` | `Authorization` (JWT) | `LIVEKIT_API_SECRET` | LiveKit `webhook.urls` config |

Configure each upstream service to `POST` to `https://<your-api-host>/integrations/webhooks/<provider>` with the matching header.

## Cal.com

### `POST /integrations/webhooks/calcom`

Auth: `x-cal-secret-key` header, verified against `CALCOM_WEBHOOK_SECRET`.

Event types handled (event type is read from `body.triggerEvent || body.event`):

| Event type | Side effect |
|---|---|
| `BOOKING_CREATED`, `BOOKING_CONFIRMED` | Sets matching `Booking.isConfirmed = true` |
| `BOOKING_CANCELLED`, `BOOKING_REJECTED` | Sets matching `Booking.isConfirmed = false` |
| `BOOKING_RESCHEDULED` | Updates `Booking.startTime` and `Booking.endTime` |
| `BOOKING_NO_SHOW` | Logged; no schema change (Booking has no no-show field) |
| `BOOKING_ATTENDEE_ADDED`, `BOOKING_ATTENDEE_REMOVED` | Logged; future: sync to episode guests |
| Other | Debug-logged |

Booking is resolved by matching the Cal.com UID against `Booking.calendarEventId` or a substring of `Booking.meetLink`.

## Chatwoot

### `POST /integrations/webhooks/chatwoot/:accountId`

Auth: `x-chatwoot-signature` header, verified against `CHATWOOT_WEBHOOK_SECRET`.

`:accountId` is the Chatwoot account ID (also configurable via `CHATWOOT_ACCOUNT_ID` env). Multiple accounts supported by routing through the path param.

Event types handled (read from `body.event`):

| Event | Side effect |
|---|---|
| `message_created` (incoming) | Logs conversation + contact IDs; calls `syncChatwootContact(contactId, accountId)` |
| `conversation_created` | Logs new conversation ID |
| `conversation_status_changed` | Logs status transition |
| `contact_created`, `contact_updated` | Calls `syncChatwootContact(contactId, accountId)` |
| Other | Debug-logged |

## Documenso

### `POST /integrations/webhooks/documenso`

Auth: `x-documenso-signature` header, verified against `DOCUMENSO_WEBHOOK_SECRET`.

Patient flow: Documenso fires `document_completed` or `document_declined` when all recipients finish. MicProtocol logs the transition keyed by `documentId`; future work will store signed-doc URLs on the relevant `Booking` or custom contract model.

## Formbricks

### `POST /integrations/webhooks/formbricks`

Auth: `x-formbricks-signature` header, verified against `FORMBRICKS_WEBHOOK_SECRET`.

Event type is read from `body.event || body.type`. If the response payload carries `data.userId` matching a `Guest.id`, MicProtocol writes a `GuestJourneyEvent`:

- `eventType`: `follow_up`
- `title`: `"Completed Survey"`
- `details`: `"Completed survey <surveyId>"`
- `metadata`: `body.data`

This is what powers the "guest completed the post-interview NPS" timeline entry.

## Listmonk

### `POST /integrations/webhooks/listmonk`

Auth: `x-listmonk-secret` header, verified against `LISTMONK_WEBHOOK_SECRET`.

Confirmed in Listmonk Admin → Settings → Webhooks with the matching secret header (`x-listmonk-secret`).

Event types handled (read from `body.event`):

| Event | Side effect |
|---|---|
| `subscriber.created`, `subscriber.updated` | Calls `syncListmonkSubscriber(subscriber)` — upserts `Guest.customFields` with `{ listmonkSubscriberId, listmonkStatus, listmonkLists }` |
| `subscriber.deleted` | Calls `unsubscribeListmonkSubscriber(email)` — stamps `Guest.customFields.listmonkUnsubscribedAt` |
| `subscriber.subscribed`, `subscriber.unsubscribed` | Calls `handleListmonkSubscriptionChange(email, lists, event)` — logs list membership transitions |
| Other | Debug-logged |

## LiveKit

### `POST /integrations/webhooks/livekit`

Auth: `Authorization` JWT signed with `LIVEKIT_API_SECRET`. The handler checks for either a valid `Authorization` header or a `body.event` payload (defensive — some LiveKit versions send the event in the body without a JWT in dev).

Event types handled (read from `body.event`):

| Event | Side effect |
|---|---|
| `room_finished` | Sets matching `RecordingSession.status = "completed"` and `endedAt = now()`. Session is resolved by matching `body.room.name` against `RecordingSession.episodeId`. |
| `participant_joined`, `participant_left` | Logs participant identity + room name |
| Other | Debug-logged |

This is the trigger that flips an episode from "recording" to "recorded" and unlocks the Content Studio domain (see [Domain Workflows](./workflows.md)).

## Securing Webhooks in Production

1. **TLS only** — terminate TLS at the API or a reverse proxy; never expose webhooks over plain HTTP.
2. **Set every `*_WEBHOOK_SECRET`** — empty values silently disable verification. Always generate with `openssl rand -hex 32` (see [`scripts/generate-secrets.sh`](../scripts/generate-secrets.sh)).
3. **Sync secrets on both sides** — when you rotate `FORMBRICKS_WEBHOOK_SECRET`, update both `.env` and the Formbricks Admin UI in the same change window.
4. **Restrict by source IP** — if your upstream integration publishes source IPs, add an IP allowlist at the network edge (nginx, Cloudflare, security group).
5. **Idempotency TTL** — `WebhookIdempotencyService` keys live in Redis; confirm your Redis eviction policy isn't aggressively evicting webhook keys during spike traffic (default `allkeys-lru` is safe for typo retries but not for long-delayed redeliveries).
6. **Monitor 401 rates** — a spike in `UnauthorizedException` from the webhook controller means a secret mismatch (rotated on one side only) or an attacker probing. See [Operations Runbook → Monitoring](./operations-runbook.md#monitoring).
7. **Log all events** — the controller logs every received event at `info` level. Aggregate these into your APM for a complete "what happened in my integrations" timeline.