feat: add CW callback route and optimize cache refresh workflows

API_ROUTES.md

@@ -32,6 +32,56 @@ See [PERMISSIONS.md](PERMISSIONS.md) for the full list of field-level permission
 
 ## Authentication Routes
 
+## ConnectWise Callback Routes
+
+### Receive ConnectWise Callback
+
+**POST** `/cw/callback/:secret/:resource`
+
+Receives ConnectWise callback/webhook payloads for supported resources and returns a normalized success response.
+
+**Authentication Required:** No
+
+**Path Parameters:**
+
+- `secret` — Shared callback secret, validated against `CW_CALLBACK_SECRET` when configured
+- `resource` — one of: `opportunity`, `ticket`, `company`, `activity`
+
+**Behavior:**
+
+- Parses JSON request body when present.
+- Decodes JSON-encoded payload fields such as `Entity`.
+- Logs a concise callback summary to console.
+
+**Response:**
+
+```json
+{
+  "status": 200,
+  "message": "CW callback received.",
+  "data": {
+    "resource": "ticket",
+    "summary": {
+      "resource": "ticket",
+      "messageId": "1bec7421-204a-4b30-8b06-465915e9a0f5",
+      "action": "updated",
+      "type": "ticket",
+      "id": 36073,
+      "memberId": "jroberts",
+      "entityStatus": "In Progress",
+      "entitySummary": "Onsite Installation: Rough-In",
+      "entityUpdatedBy": "cirvine",
+      "entityLastUpdated": "2026-03-03T21:43:29.903"
+    },
+    "bodyParsed": {},
+    "receivedAt": "2026-03-04T00:00:00.000Z"
+  },
+  "successful": true
+}
+```
+
+---
+
 ### Get Authentication URI
 
 **GET** `/auth/uri`