Webhook versioning docs

api-reference/webhooks/versions.mdx

@@ -0,0 +1,106 @@
+---
+title: 'Webhook Versions'
+sidebarTitle: 'Webhook Versions'
+---
+
+Webhook versioning in Plain ensures that your endpoint consistently receives webhook payloads in a predictable format. This document explains how webhook versioning works, the available versions, and how to upgrade to the latest version.
+
+## Understanding Webhook Versions
+
+Every [webhook target](https://www.plain.com/docs/api-reference/webhooks#receiving-events-from-plain) in Plain is associated with a specific version. The webhook version defines the schema of the payload that Plain sends to your endpoint. By specifying a version, you ensure that the payload format remains consistent, even as Plain evolves and introduces changes to the webhook schema.
+
+**Benefits of Versioning**:
+
+- **Consistency**: Your endpoint always receives payloads in the same format.
+- **Control**: You decide when to adopt new schema changes.
+- **Stability**: Prevents unexpected breaking changes due to schema updates.
+
+## Available Versions
+
+We recommend always using the latest version of the webhook payload schema to benefit from new features and improvements. Below are the currently available versions:
+
+### `2024-09-18` (Latest)
+
+Our first official versioned webhook payload schema.
+
+- **What's New**:
+  - Introduction of webhook versioning.
+  - Improved forward-compatibility schema definitions for payloads.
+  - Microsoft Teams events.
+  - New thread status details.
+- [View JSON Schema](https://core-api.uk.plain.com/webhooks/schema/2024-09-18.json)
+- **TypeScript SDK Compatibility**: Version `>= 5.0.0`
+
+### `unversioned`
+The legacy webhook payload schema before versioning was implemented.
+- [View JSON Schema](https://core-api.uk.plain.com/webhooks/schema/unversioned.json)
+- **TypeScript SDK Compatibility**: Versions `>= 4.8.0` and `< 5.0.0`
+
+## How to Upgrade to the Latest Version
+
+Upgrading to the latest webhook version involves updating your code to handle the new schema and changing your webhook target settings in Plain.
+
+### Step 1: Update Your Code
+Modify your code to handle both the old and new webhook payload versions during the transition period. This ensures uninterrupted processing of events.
+
+**Handle Version Mismatch (TypeScript SDK Users):**
+
+If you're using our TypeScript SDK, you can update your code to throw an error when receiving an old version. This will cause Plain to retry the request later, ideally after you've updated the webhook target version in the Plain dashboard. For more details, refer to our [retry policy](https://www.plain.com/docs/api-reference/webhooks#retry-policy).
+
+See the [TypeScript SDK Example](#typescript-sdk-example) for implementation details.
+
+Deploy this updated code, and fast follow with Step 2.
+
+### Step 2: Update the Webhook Target in Plain
+
+After deploying your updated code, change the version of your webhook target in Plain to the new version. This ensures that all future webhook events are sent using the latest schema.
+
+### Step 3: Revert Temporary Code Changes
+
+Once you have confirmed that your application is successfully processing events with the new version, you can remove the code that handles both old and new versions. Your code can now exclusively handle the latest webhook payload schema.
+
+<Info>Ensure that your webhook handling code is **idempotent** and can gracefully handle **duplicate events**. Plain's webhook delivery is **at least once**, meaning the same event might be delivered multiple times. Refer to our [delivery semantics](https://www.plain.com/docs/api-reference/webhooks#delivery-semantics) for more information.</Info>
+
+## TypeScript SDK Example
+
+Below is an example of how to handle webhook version mismatches using our TypeScript SDK:
+
+```typescript
+import {
+  verifyPlainWebhook,
+  PlainWebhookVersionMismatchError,
+} from '@team-plain/typescript-sdk';
+
+// The same approach works for `parsePlainWebhook`
+const webhookResult = verifyPlainWebhook(payload, signature, secret);
+
+if (webhookResult.error instanceof PlainWebhookVersionMismatchError) {
+  // Received a webhook with an old version
+  // Return a non-2XX response to trigger a retry
+  throw new Error("Skipping older version");
+}
+
+// proceed with the rest of your error handling logic
+```
+
+**Explanation**:
+
+- **Version Mismatch Handling**: By checking if the error is an instance of `PlainWebhookVersionMismatchError`, you can determine if the payload is on the old version. This could happen if an event is sent during the time between your code deployment and the webhook target version update in Plain.
+- **Triggering a Retry**: Throwing an error or returning a non-2XX HTTP response tells Plain to retry the webhook delivery later. After you update the webhook target version in Plain, the failed event will be resent with the new schema.
+
+## Identifying the Webhook Version in Received Payloads
+
+If you receive a webhook payload and are unsure which version it is using, you can identify the version by checking:
+
+- **Headers**: The `Plain-Webhook-Target-Version` header indicates the version of the webhook target for which this request is intended.
+- **Payload Metadata**: Within the [webhook metadata](https://www.plain.com/docs/api-reference/webhooks#webhook-metadata) in the payload body, the `webhookTargetVersion` field specifies the version of the webhook target for this request.
+
+This information helps you determine how to parse and handle the webhook payload according to its schema version.
+
+## Best Practices and Recommendations
+
+- **Monitor Logs**: After upgrading, monitor your logs and error tracking systems for any issues related to webhook processing.
+- **Stay Informed**: Keep an eye on our documentation and [change log](https://www.plain.com/changelog) for future updates or changes to the webhook schema.
+
+
+If you have any questions or need assistance, please reach out to us at **[[email protected]](mailto:[email protected])**.

mint.json

@@ -250,6 +250,7 @@
 					"group": "Webhooks",
 					"pages": [
 						"api-reference/webhooks",
+						"api-reference/webhooks/versions",
 						"api-reference/webhooks/typescript",
 						"api-reference/webhooks/thread-created",
 						"api-reference/webhooks/thread-status-transitioned",
@@ -303,4 +304,4 @@
 			"destination": "/headless-support-portal"
 		}
 	]
-}
+}