Skip to main content
Every webhook target 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-02-11 (Latest)

  • What’s New:
    • Added numberValue field to threadField.
    • Added NUMBER to the threadField.type enum.
  • View JSON Schema

​
2025-08-06

  • What’s New:
    • Added additionalAssignees to thread.
    • Added externalId and isExcludedFromAi fields to labelType.
  • View JSON Schema

​
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

​
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

​
unversioned

The legacy webhook payload schema before versioning was implemented.

​
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.
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 for more information.

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