> ## Documentation Index
> Fetch the complete documentation index at: https://www.plain.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Versions

Every [webhook target](https://www.plain.com/docs/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:

### `2026-05-06` (Latest)

* **What's New**:
  * Added `numberValue` field to `threadField`.
  * Added `NUMBER` to the `threadField.type` enum.
* [View JSON Schema](https://core-api.uk.plain.com/webhooks/schema/2026-05-06.json)

### `2025-08-06`

* **What's New**:
  * Added `additionalAssignees` to `thread`.
  * Added `externalId` and `isExcludedFromAi` fields to `labelType`.
* [View JSON Schema](https://core-api.uk.plain.com/webhooks/schema/2025-08-06.json)

### `2025-07-30`

* **What's New**:
  * `threadField.createdBy` and `threadField.updatedBy` changed from `internalActor` to `actor` (now supports customer and other actor types).
* [View JSON Schema](https://core-api.uk.plain.com/webhooks/schema/2025-07-30.json)

### `2024-09-18`

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)

### `unversioned`

The legacy webhook payload schema before versioning was implemented.

* [View JSON Schema](https://core-api.uk.plain.com/webhooks/schema/unversioned.json)

## 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.

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/webhooks#delivery-semantics) for more
  information.
</Info>

## 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/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 **[help@plain.com](mailto:help@plain.com)**.