Updated dependencies, webhook payloads, hints for agents

.cursor/rules/webhooks.md

@@ -0,0 +1,11 @@
+---
+description: Updating webhook documentation, snippets, and versions
+globs:
+  - "_snippets/webhooks/**"
+  - "webhooks/**"
+  - "scripts/validateWebhookSnippets.ts"
+---
+
+# Webhook Documentation
+
+For the full guide on updating webhook snippets and versions, see [AGENTS.md](../../AGENTS.md) in the repo root.

.mintignore

@@ -0,0 +1,2 @@
+AGENTS.md
+.cursor/

AGENTS.md

@@ -0,0 +1,82 @@
+# Webhook Documentation Update Guide
+
+This document describes how to update webhook snippet examples and the versions page when a new webhook schema version is released.
+
+## Overview
+
+- Webhook example payloads live in `_snippets/webhooks/*.mdx`. Each file contains a single JSON code block with an example payload for one webhook event type.
+- The webhook versions changelog lives in `webhooks/versions.mdx`.
+- Snippets are validated against the **latest** schema at `https://core-api.uk.plain.com/webhooks/schema/latest.json` using the `pnpm lint:snippets` command (which runs `scripts/validateWebhookSnippets.ts`).
+- Versioned schemas are available at `https://core-api.uk.plain.com/webhooks/schema/<version>.json` (e.g. `2026-02-11.json`).
+
+## Typical prompt
+
+> Please update the documentation for webhook version `<version>`
+
+## Step-by-step process
+
+### 1. Fetch the new and previous schemas
+
+Fetch the JSON schemas for the new version and the previous version to diff them:
+
+- New: `https://core-api.uk.plain.com/webhooks/schema/<new-version>.json`
+- Previous: the most recent version listed in `webhooks/versions.mdx`
+
+### 2. Identify changes between versions
+
+Compare the two schemas and note:
+
+- **New fields added** to existing definitions (e.g. a new field on `threadField`, `thread`, `customer`, `labelType`, etc.)
+- **Fields removed** from existing definitions
+- **Type changes** (e.g. `internalActor` → `actor`, new enum values)
+- **New event types** added to the `type` enum or new payload definitions
+- **Removed event types**
+
+### 3. Run the snippet linter
+
+```bash
+pnpm lint:snippets
+```
+
+This validates every file in `_snippets/webhooks/` against the latest schema. Any failing snippets will be reported with the specific validation error (e.g. missing required field, wrong type).
+
+Fix **all** reported errors before proceeding.
+
+### 4. Fix failing snippets
+
+For each failing snippet in `_snippets/webhooks/`:
+
+- Open the file and find the JSON payload inside the `` ```json `` code block.
+- Cross-reference with the schema definition for that event type. The `eventType` field in the payload tells you which schema definition to look at.
+- Common fixes:
+  - **Missing required field**: Add the field with an appropriate example value (use `null` for nullable fields that don't apply to the example).
+  - **Wrong field names**: Always check the schema for the correct field names. For example, each actor type has its own ID field — look up the relevant actor definition in the schema.
+  - **New enum value**: If a type enum was expanded, no snippet changes are usually needed unless an existing value was removed.
+- When in doubt, fetch the schema and look up the `required` array for the relevant definition.
+
+### 5. Re-run the linter
+
+```bash
+pnpm lint:snippets
+```
+
+Confirm all snippets pass. If any still fail, repeat step 4.
+
+### 6. Update `webhooks/versions.mdx`
+
+Add a new `### \`<version>\` (Latest)` section **above** the previous latest version. Remove the `(Latest)` label from the old one.
+
+Each version entry should include:
+
+- A concise bulleted list of what changed (fields added/removed, type changes, new events)
+- A link to the JSON schema: `[View JSON Schema](https://core-api.uk.plain.com/webhooks/schema/<version>.json)`
+
+Keep the descriptions brief — a few bullet points on fields/events added, removed, or changed.
+
+### 7. Final check
+
+Run the full linter one more time to make sure nothing is broken:
+
+```bash
+pnpm lint:snippets
+```

_snippets/webhooks/customer-created.mdx

@@ -32,7 +32,7 @@
   "id": "pEv_01HD44FHDPMZ3YJB5GEB1EZKQV",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HD44FJ45FJKVFHM3MDVYPGRS",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2023-10-19T14:12:25.861Z"

_snippets/webhooks/customer-deleted.mdx

@@ -32,7 +32,7 @@
   "id": "pEv_01HD442MG86ATWJ2MDEYCV6VPV",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HD444M37N1HYFVJ92DA05BQK",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2023-10-19T14:06:27.431Z"

_snippets/webhooks/customer-group-changed.mdx

@@ -90,7 +90,7 @@
   "id": "pEv_01HD4DZQ153AE8FK17TFJ7PC01",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HD4DZQD334K6KX0ER03JWDAR",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2023-10-19T16:58:32.739Z"

_snippets/webhooks/customer-updated.mdx

@@ -59,7 +59,7 @@
   "id": "pEv_01HD450JT0RPBT7RRKS1ZQJYBA",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HD450N6X782MDTDBMS6Z14DJ",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2023-10-19T14:21:46.077Z"

_snippets/webhooks/thread-assignment-transitioned.mdx

@@ -151,7 +151,7 @@
   "id": "pEv_01HD4X7BTCJSP3NGTBKYSWGPSY",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HD4XHSAX79QW8E34V86CKJRK",
     "webhookDeliveryAttemptNumber": 4,
     "webhookDeliveryAttemptTimestamp": "2023-10-19T21:30:33.181Z"

_snippets/webhooks/thread-chat-received.mdx

@@ -13,12 +13,12 @@
       "createdAt": "2023-11-02T15:32:28.831Z",
       "createdBy": {
         "actorType": "customer",
-        "userId": "c_01HDRC3CJHBWBAAF4K63Z11XZ5"
+        "customerId": "c_01HDRC3CJHBWBAAF4K63Z11XZ5"
       },
       "updatedAt": "2023-11-02T15:32:28.831Z",
       "updatedBy": {
         "actorType": "customer",
-        "userId": "c_01HDRC3CJHBWBAAF4K63Z11XZ5"
+        "customerId": "c_01HDRC3CJHBWBAAF4K63Z11XZ5"
       }
     },
     "thread": {
@@ -93,7 +93,7 @@
   "id": "pEv_01HE8AM6GZVS1S3609PFGR30FE",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HE8ANGEGVQVTCY3DD30CZ8G4",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2023-11-02T15:33:11.760Z"

_snippets/webhooks/thread-chat-sent.mdx

@@ -93,7 +93,7 @@
   "id": "pEv_01HE8AM6GZVS1S3609PFGR30FE",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HE8ANGEGVQVTCY3DD30CZ8G4",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2023-11-02T15:33:11.760Z"

_snippets/webhooks/thread-created.mdx

@@ -67,7 +67,7 @@
   "id": "pEv_01HD44FHHJ0YABSNGKWMG3CJ5J",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HD44FJASQM23MNHYDYPAXEG8",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2023-10-19T14:12:26.073Z"

_snippets/webhooks/thread-email-received.mdx

@@ -109,7 +109,7 @@
   "id": "pEv_01HD44FJ053ZHW13SWS9556THX",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HD44SZM21CPW0MXEQ73C2X7C",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2023-10-19T14:18:07.362Z"

_snippets/webhooks/thread-email-sent.mdx

@@ -112,7 +112,7 @@
   "id": "pEv_01HD4YAEHDHS2FW3F3VRSEGGVF",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HD4YAFB6VN6AJ4TGVY4DJ0VR",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2023-10-19T21:44:02.150Z"

_snippets/webhooks/thread-field-created.mdx

@@ -76,6 +76,7 @@
       "type": "ENUM",
       "stringValue": "BUG",
       "booleanValue": null,
+      "numberValue": null,
       "createdAt": "2024-04-24T12:28:52.946Z",
       "createdBy": {
         "actorType": "system",
@@ -91,7 +92,7 @@
   "id": "pEv_01HW8192TJ5YFJ3PJG3F5NTTKX",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HW8135F4ZMA6C031MM6ZTFC4",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HW81936VC3T1KD1PJN3J9KXA",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2024-04-24T12:28:53.339Z"

_snippets/webhooks/thread-field-deleted.mdx

@@ -73,6 +73,7 @@
       "type": "ENUM",
       "stringValue": "QUESTION",
       "booleanValue": null,
+      "numberValue": null,
       "createdAt": "2024-04-24T12:26:58.407Z",
       "createdBy": {
         "actorType": "system",
@@ -88,7 +89,7 @@
   "id": "pEv_01HW81VG2KXEC4P9DFG4F53SGP",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HW8135F4ZMA6C031MM6ZTFC4",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HW81VGMYPPVTW8HMT31AFFGV",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2024-04-24T12:38:56.926Z"

_snippets/webhooks/thread-field-updated.mdx

@@ -73,6 +73,7 @@
       "type": "ENUM",
       "stringValue": "PRICING",
       "booleanValue": null,
+      "numberValue": null,
       "createdAt": "2024-04-24T12:26:58.407Z",
       "createdBy": {
         "actorType": "system",
@@ -91,6 +92,7 @@
       "type": "ENUM",
       "stringValue": "QUESTION",
       "booleanValue": null,
+      "numberValue": null,
       "createdAt": "2024-04-24T12:26:58.407Z",
       "createdBy": {
         "actorType": "system",
@@ -106,7 +108,7 @@
   "id": "pEv_01HW81JM6HHT2DHR7BWMJDCP05",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HW8135F4ZMA6C031MM6ZTFC4",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HW81JMQARPYWWHV03JPYT53Y",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2024-04-24T12:34:06.186Z"

_snippets/webhooks/thread-labels-changed.mdx

@@ -165,7 +165,7 @@
   "id": "pEv_01HD4Y12QZ1X7FQN2648JCVMN4",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HD4Y15J3HJ2BFDGXTGWSC2XC",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2023-10-19T21:38:57.219Z"

_snippets/webhooks/thread-note-created.mdx

@@ -94,7 +94,7 @@
   "id": "pEv_01HE86SY5A9KKTACZW3FGQJ0CS",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HE86V6GP2JZCQ3D6AXK81TWD",
     "webhookDeliveryAttemptNumber": 3,
     "webhookDeliveryAttemptTimestamp": "2023-11-02T14:26:23.894Z"

_snippets/webhooks/thread-service-level-agreement-status-transitioned.mdx

@@ -114,7 +114,7 @@
   "id": "pEv_01HD4X6WMCJSD8EHWDRHZ8WYDT",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HD4XH9YE8CK6KT3G8VRX38R7",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2023-10-19T21:30:17.422Z"

_snippets/webhooks/thread-slack-message-received.mdx

@@ -136,7 +136,7 @@
   "id": "pEv_01J0QRQN0Z96DNVFAFDNFAX8QQ",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01J0QRJ785442SC6Z4RR6CAR2J",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01J0QRQNMBQCV6JW43B59FCJ8D",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2024-06-19T08:10:11.979Z"

_snippets/webhooks/thread-slack-message-sent.mdx

@@ -93,7 +93,7 @@
   "id": "pEv_01J0QRMYED7BE28DR5J8SHV9P4",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01J0QRJ785442SC6Z4RR6CAR2J",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01J0QRMZ43VXY2Q2KGBF5BET47",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2024-06-19T08:08:43.395Z"

_snippets/webhooks/thread-status-transitioned.mdx

@@ -132,7 +132,7 @@
   "id": "pEv_01HD4X6WMCJSD8EHWDRHZ8WYDT",
   "webhookMetadata": {
     "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    "webhookTargetVersion": "2024-09-18",
+    "webhookTargetVersion": "2026-02-11",
     "webhookDeliveryAttemptId": "whAttempt_01HD4XH9YE8CK6KT3G8VRX38R7",
     "webhookDeliveryAttemptNumber": 1,
     "webhookDeliveryAttemptTimestamp": "2023-10-19T21:30:17.422Z"

package.json

@@ -14,17 +14,15 @@
 		"lint:links": "mintlify broken-links",
 		"lint:biome": "biome check",
 		"lint:fix": "biome check --write",
-		"format": "prettier --write './**/*.{js,ts,tsx,md,mdx}'"
-	},
-	"dependencies": {
-		"ajv-formats": "^3.0.1",
-		"mintlify": "^4.2.31"
+		"format:fix": "biome format --write ."
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^1.9.4",
-		"@types/ajv": "^1.0.0",
-		"@types/node": "^22.5.5",
-		"ajv": "^8.17.1",
-		"tsx": "^4.19.1"
+		"@biomejs/biome": "1.9.4",
+		"mintlify": "4.2.342",
+		"form-data": "4.0.5",
+		"@types/node": "22.5.5",
+		"ajv": "8.17.1",
+		"ajv-formats": "3.0.1",
+		"tsx": "4.21.0"
 	}
 }