Webhooks

Receive inbound events from external systems into DocsChat.

Requirements

Standard+ plan (apiAccess)
Workspace webhook secret (shown in Admin → API settings)

Authentication

Every request must include:

x-webhook-secret: YOUR_WORKSPACE_SECRET

Missing or invalid secret → 401.

Endpoint

POST /api/webhooks/inbound
x-webhook-secret: whsec_xxxxx
Content-Type: application/json

{
  "event": "chat.message",
  "sessionId": "clxx...",
  "message": "User message from external system"
}

Response `200`

{
  "received": true,
  "workspaceId": "..."
}

Supported events

Event	Behavior
`chat.message`	Appends USER message to session if session belongs to workspace
Other	Logged; acknowledged

Extend the handler in src/app/api/webhooks/inbound/route.ts for custom events.

Secret rotation

Generate a new secret for the workspace
Update integrator configuration
Monitor logs for 401 from the old secret
Remove the old secret after a grace period

Never commit webhook secrets to version control.

Plan enforcement

Free and Hobby workspaces receive 403 — upgrade to Standard+.

REST API integration
Repo: docs/api/webhooks-inbound.md