Update webhooks package to latest schema version

mattvagni · mattvagni · commit 163aa221d5e3 · 2026-03-25T22:35:57.000+01:00
Update webhook JSON schema and TypeScript types to match the latest
Plain API version. Update tests for new schema shape.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -17,6 +17,8 @@ pnpm check            # Format + lint with biome (auto-fix)
 
 Per-package scripts (codegen, test, etc.) are run via `pnpm --filter <pkg> <script>`.
 
+**Always run `pnpm check` after making any changes.** This auto-fixes formatting and linting issues. CI enforces both via `pnpm format:check` and `pnpm lint`, so unformatted or unlinted code will fail the build.
+
 ## Architecture
 
 Four packages in a pnpm monorepo:
@@ -72,9 +74,7 @@ Edit files in `packages/sdk/src/`, export from `index.ts`, then `pnpm build`.
 
 **Update the webhook schema:**
 ```bash
-curl -o packages/webhooks/src/webhook-schema.json https://core-api.uk.plain.com/webhooks/schema/latest.json
-# Regenerate TypeScript types from the JSON schema (requires json-schema-to-typescript)
-npx json-schema-to-typescript --input packages/webhooks/src/webhook-schema.json --output packages/webhooks/src/webhook-schema.ts
+pnpm --filter @team-plain/webhooks codegen
 pnpm --filter @team-plain/webhooks build
 pnpm --filter @team-plain/webhooks test
 ```
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -90,6 +90,7 @@ Files prefixed with `_generated_` are auto-generated — don't edit them manuall
 | `pnpm --filter @team-plain/sdk build` | Build just the SDK |
 | `pnpm --filter @team-plain/ui-components build` | Build just ui-components |
 | `pnpm --filter @team-plain/ui-components test` | Test ui-components |
+| `pnpm --filter @team-plain/webhooks codegen` | Fetch + regenerate webhook schema types |
 | `pnpm --filter @team-plain/webhooks build` | Build just webhooks |
 | `pnpm --filter @team-plain/webhooks test` | Test webhooks |
 | `pnpm format` | Format with biome |
@@ -131,8 +132,7 @@ Edit files in `packages/sdk/src/`, export from `index.ts`, then `pnpm build`.
 ### Update the webhook schema
 
 ```bash
-curl -o packages/webhooks/src/webhook-schema.json https://core-api.uk.plain.com/webhooks/schema/latest.json
-npx json-schema-to-typescript --input packages/webhooks/src/webhook-schema.json --output packages/webhooks/src/webhook-schema.ts
+pnpm --filter @team-plain/webhooks codegen
 pnpm --filter @team-plain/webhooks build
 pnpm --filter @team-plain/webhooks test
 ```
diff --git a/packages/webhooks/CHANGELOG.md b/packages/webhooks/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @team-plain/webhooks
 
+## 0.2.0
+
+### Minor Changes
+
+- af22f5f: Update webhooks parsing to latest webhook version.
+
 ## 0.1.1
 
 ### Patch Changes
diff --git a/packages/webhooks/package.json b/packages/webhooks/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@team-plain/webhooks",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,14 +18,16 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "vitest run"
+    "test": "vitest run",
+    "codegen": "sh ./scripts/codegen-webhooks.sh"
   },
   "dependencies": {
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1"
   },
   "devDependencies": {
     "@types/node": "^25.0.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "json-schema-to-typescript": "^13.1.2"
   }
 }
diff --git a/packages/webhooks/scripts/codegen-webhooks.sh b/packages/webhooks/scripts/codegen-webhooks.sh
@@ -0,0 +1,6 @@
+
+#!/bin/bash
+# Download the JSON schema
+curl https://core-api.uk.plain.com/webhooks/schema/latest.json -o ./src/webhook-schema.json
+
+./node_modules/.bin/json2ts --input ./src/webhook-schema.json --output ./src/webhook-schema.ts
diff --git a/packages/webhooks/src/__tests__/verify-plain-webhook.test.ts b/packages/webhooks/src/__tests__/verify-plain-webhook.test.ts
@@ -47,7 +47,7 @@ describe("verifyPlainWebhook", () => {
   it("returns an error when the signature matches but the timestamp is too far in the past", () => {
     const result = verifyPlainWebhook(
       JSON.stringify(threadCreatedPayload),
-      "ae0d54c966dea1056b6ced04d1bafc3358af592469b5fd55553dcb036b58a1ef",
+      "41a425d490211cba1258f0c35dba59db36273ffae49052be0e6c13a518927fd1",
       "secret",
     );
 
@@ -63,7 +63,7 @@ describe("verifyPlainWebhook", () => {
 
     const result = verifyPlainWebhook(
       JSON.stringify(threadCreatedPayload),
-      "ae0d54c966dea1056b6ced04d1bafc3358af592469b5fd55553dcb036b58a1ef",
+      "41a425d490211cba1258f0c35dba59db36273ffae49052be0e6c13a518927fd1",
       "secret",
     );
 
@@ -96,7 +96,7 @@ describe("verifyPlainWebhook", () => {
 
     const result = verifyPlainWebhook(
       JSON.stringify(invalidPayload),
-      "5656d05d265cea83d60afe94b440eff2ef403a8d77f6bf5483e5e83f3e5b1499",
+      "9495c54afef3630ef0135dad8efc27b298926412827cc8d7f5108b7e737a6850",
       "secret",
     );
 
diff --git a/packages/webhooks/src/__tests__/webhook-payloads/customer-created.ts b/packages/webhooks/src/__tests__/webhook-payloads/customer-created.ts
@@ -31,7 +31,7 @@ export default {
   id: "pEv_01HD44FHDPMZ3YJB5GEB1EZKQV",
   webhookMetadata: {
     webhookTargetId: "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    webhookTargetVersion: "2026-02-27",
+    webhookTargetVersion: "2026-03-13",
     webhookDeliveryAttemptId: "whAttempt_01HD44FJ45FJKVFHM3MDVYPGRS",
     webhookDeliveryAttemptNumber: 1,
     webhookDeliveryAttemptTimestamp: "2023-10-19T14:12:25.861Z",
diff --git a/packages/webhooks/src/__tests__/webhook-payloads/email-received.ts b/packages/webhooks/src/__tests__/webhook-payloads/email-received.ts
@@ -106,7 +106,7 @@ export default {
   id: "pEv_01HR9W91EMR655WS6VC2867D3C",
   webhookMetadata: {
     webhookTargetId: "whTarget_01HR9VYX2GYKX1XCTFXRG1K3MX",
-    webhookTargetVersion: "2026-02-27",
+    webhookTargetVersion: "2026-03-13",
     webhookDeliveryAttemptId: "whAttempt_01HR9W92RSJZA4011XDNHJ5VK7",
     webhookDeliveryAttemptNumber: 1,
     webhookDeliveryAttemptTimestamp: "2024-03-06T12:37:11.577Z",
diff --git a/packages/webhooks/src/__tests__/webhook-payloads/invalid.ts b/packages/webhooks/src/__tests__/webhook-payloads/invalid.ts
@@ -48,7 +48,7 @@ export default {
   id: "pEv_01HR9W25SFVMS2Y4Q8W75M86G4",
   webhookMetadata: {
     webhookTargetId: "whTarget_01HR9VYX2GYKX1XCTFXRG1K3MX",
-    webhookTargetVersion: "2026-02-27",
+    webhookTargetVersion: "2026-03-13",
     webhookDeliveryAttemptId: "whAttempt_01HR9W26906XCJ64JQZG8RJCCQ",
     webhookDeliveryAttemptNumber: 1,
     webhookDeliveryAttemptTimestamp: "2024-03-06T12:33:25.792Z",
diff --git a/packages/webhooks/src/__tests__/webhook-payloads/thread-assignment-transitioned.ts b/packages/webhooks/src/__tests__/webhook-payloads/thread-assignment-transitioned.ts
@@ -39,7 +39,7 @@ export default {
       statusDetail: null,
       assignee: null,
       assignedAt: null,
-      additionalAsignees: [],
+      additionalAssignees: [],
       labels: [],
       firstInboundMessageInfo: {
         timestamp: "2024-03-06T12:32:05.710Z",
@@ -112,7 +112,7 @@ export default {
         deletedBy: null,
       },
       assignedAt: "2024-03-06T12:34:44.535Z",
-      additionalAsignees: [],
+      additionalAssignees: [],
       labels: [],
       firstInboundMessageInfo: {
         timestamp: "2024-03-06T12:32:05.710Z",
@@ -134,7 +134,7 @@ export default {
   id: "pEv_01HR9W4K5QEVAFQSYCKN2D8198",
   webhookMetadata: {
     webhookTargetId: "whTarget_01HR9VYX2GYKX1XCTFXRG1K3MX",
-    webhookTargetVersion: "2026-02-27",
+    webhookTargetVersion: "2026-03-13",
     webhookDeliveryAttemptId: "whAttempt_01HR9W4KV3RHX435FPZJ46P5WY",
     webhookDeliveryAttemptNumber: 1,
     webhookDeliveryAttemptTimestamp: "2024-03-06T12:34:45.219Z",
diff --git a/packages/webhooks/src/__tests__/webhook-payloads/thread-created.ts b/packages/webhooks/src/__tests__/webhook-payloads/thread-created.ts
@@ -67,7 +67,7 @@ export default {
   id: "pEv_01HD44FHHJ0YABSNGKWMG3CJ5J",
   webhookMetadata: {
     webhookTargetId: "whTarget_01HD4400VTDJQ646V6RY37SR7K",
-    webhookTargetVersion: "2026-02-27",
+    webhookTargetVersion: "2026-03-13",
     webhookDeliveryAttemptId: "whAttempt_01HD44FJASQM23MNHYDYPAXEG8",
     webhookDeliveryAttemptNumber: 1,
     webhookDeliveryAttemptTimestamp: "2023-10-19T14:12:26.073Z",
diff --git a/packages/webhooks/src/__tests__/webhook-payloads/thread-status-transitioned.ts b/packages/webhooks/src/__tests__/webhook-payloads/thread-status-transitioned.ts
@@ -115,7 +115,7 @@ export default {
   id: "pEv_01HR9W25SFVMS2Y4Q8W75M86G4",
   webhookMetadata: {
     webhookTargetId: "whTarget_01HR9VYX2GYKX1XCTFXRG1K3MX",
-    webhookTargetVersion: "2026-02-27",
+    webhookTargetVersion: "2026-03-13",
     webhookDeliveryAttemptId: "whAttempt_01HR9W26906XCJ64JQZG8RJCCQ",
     webhookDeliveryAttemptNumber: 1,
     webhookDeliveryAttemptTimestamp: "2024-03-06T12:33:25.792Z",
diff --git a/packages/webhooks/src/index.ts b/packages/webhooks/src/index.ts
@@ -1,12 +1,12 @@
-export { parsePlainWebhook } from "./parse.js";
-export { verifyPlainWebhook } from "./verify.js";
 export {
   PlainWebhookError,
+  PlainWebhookPayloadError,
   PlainWebhookSignatureVerificationError,
   PlainWebhookVersionMismatchError,
-  PlainWebhookPayloadError,
 } from "./errors.js";
+export { parsePlainWebhook } from "./parse.js";
 export type { Result } from "./result.js";
+export { verifyPlainWebhook } from "./verify.js";
 
 export type {
   CustomerChangedPayload,
diff --git a/packages/webhooks/src/parse.ts b/packages/webhooks/src/parse.ts
@@ -4,12 +4,12 @@ import _addFormats from "ajv-formats";
 // ajv-formats is CJS — under nodenext the default import resolves to the module namespace
 const addFormats = _addFormats as unknown as typeof _addFormats.default;
 
-import { type Result, isErr } from "./result.js";
 import {
   type PlainWebhookError,
   PlainWebhookPayloadError,
   PlainWebhookVersionMismatchError,
 } from "./errors.js";
+import { isErr, type Result } from "./result.js";
 import type { WebhooksSchemaDefinition } from "./webhook-schema.js";
 import webhookSchema from "./webhook-schema.json" with { type: "json" };
 
diff --git a/packages/webhooks/src/verify.ts b/packages/webhooks/src/verify.ts
@@ -1,12 +1,11 @@
 import * as crypto from "node:crypto";
-
-import { type Result, isErr } from "./result.js";
 import {
   type PlainWebhookError,
   PlainWebhookPayloadError,
   PlainWebhookSignatureVerificationError,
 } from "./errors.js";
 import { parsePlainWebhook } from "./parse.js";
+import { isErr, type Result } from "./result.js";
 import type { WebhooksSchemaDefinition } from "./webhook-schema.js";
 
 /**
diff --git a/packages/webhooks/src/webhook-schema.json b/packages/webhooks/src/webhook-schema.json
@@ -1189,26 +1189,28 @@
     "componentWorkflowButton": {
       "type": "object",
       "properties": {
-        "workflowButtonLabel": {
-          "type": "string",
-          "maxLength": 500
-        },
         "workflowButtonWorkflowIdentifier": {
           "type": "object",
           "properties": {
             "workflowId": {
               "type": "string"
+            },
+            "workflowKey": {
+              "type": "string"
             }
           },
-          "required": ["workflowId"],
           "additionalProperties": true
         },
+        "workflowButtonLabel": {
+          "type": "string",
+          "maxLength": 500
+        },
         "type": {
           "type": "string",
           "const": "workflowButton"
         }
       },
-      "required": ["workflowButtonLabel", "workflowButtonWorkflowIdentifier", "type"],
+      "required": ["workflowButtonWorkflowIdentifier", "workflowButtonLabel", "type"],
       "additionalProperties": true
     },
     "componentBadge": {
@@ -1291,13 +1293,13 @@
           "$ref": "#/definitions/componentLinkButton"
         },
         {
-          "$ref": "#/definitions/componentBadge"
+          "$ref": "#/definitions/componentWorkflowButton"
         },
         {
-          "$ref": "#/definitions/componentCopyButton"
+          "$ref": "#/definitions/componentBadge"
         },
         {
-          "$ref": "#/definitions/componentWorkflowButton"
+          "$ref": "#/definitions/componentCopyButton"
         }
       ]
     },
@@ -1344,6 +1346,9 @@
         {
           "$ref": "#/definitions/componentLinkButton"
         },
+        {
+          "$ref": "#/definitions/componentWorkflowButton"
+        },
         {
           "$ref": "#/definitions/componentBadge"
         },
@@ -1352,9 +1357,6 @@
         },
         {
           "$ref": "#/definitions/componentRow"
-        },
-        {
-          "$ref": "#/definitions/componentWorkflowButton"
         }
       ]
     },
@@ -1395,6 +1397,9 @@
         {
           "$ref": "#/definitions/componentLinkButton"
         },
+        {
+          "$ref": "#/definitions/componentWorkflowButton"
+        },
         {
           "$ref": "#/definitions/componentBadge"
         },
@@ -1406,9 +1411,6 @@
         },
         {
           "$ref": "#/definitions/componentContainer"
-        },
-        {
-          "$ref": "#/definitions/componentWorkflowButton"
         }
       ]
     },
@@ -2883,7 +2885,7 @@
         },
         "webhookTargetVersion": {
           "type": "string",
-          "const": "2026-02-27"
+          "const": "2026-03-13"
         },
         "webhookDeliveryAttemptId": {
           "$ref": "#/definitions/id"
@@ -3345,7 +3347,8 @@
             "MESSAGE_DELETED",
             "REACTIONS_CHANGED",
             "UNKNOWN_SLACK_MESSAGE_CHANGE_TYPE"
-          ]
+          ],
+          "default": "UNKNOWN_SLACK_MESSAGE_CHANGE_TYPE"
         },
         "thread": {
           "$ref": "#/definitions/thread"
@@ -3354,7 +3357,7 @@
           "$ref": "#/definitions/slackMessage"
         }
       },
-      "required": ["eventType", "changeType", "thread", "slackMessage"],
+      "required": ["eventType", "thread", "slackMessage"],
       "additionalProperties": true
     },
     "threadDiscordMessageReceivedEventPayload": {
diff --git a/packages/webhooks/src/webhook-schema.ts b/packages/webhooks/src/webhook-schema.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
