Skip to main content

Schema Versioning

Event payloads change over time as products add fields and model new information. Each subscription is pinned to a payload version, so a new version does not change what your endpoint receives the moment it ships. You choose when to move, within the notice period Clio gives before the version you are on is retired.

For creating and managing subscriptions, and for receiving events, see the Webhooks guide.

How Pinning Works​

Every subscription has a schema_version, a date in YYYY-MM-DD form. If you do not supply one when creating a subscription, it defaults to the latest published payload version. If you do supply one, it must be a published payload version. Any other value returns a 422 listing the published versions.

A payload version is a release of the whole platform, not of a single event. When one or more events change, Clio publishes a new version that covers every event. Events that did not change in it keep the payload they had in the previous version.

So pinning to a version gives you every event's payload as it stood in that version. If you pin to 2026-06-01 and only grow.inbox_lead.submitted changed in it, that event sends its new payload and every other event sends the same payload it did under 2026-01-01. An event added after your pin is sent in its first published payload.

Every delivery carries your subscription's pin as its schema_version, whichever event it is:

{
  "event_id": "01JA6Z3N8Q2V5W7X9Y1B3C5D7E",
  "event_type": "grow.inbox_lead.submitted",
  "schema_version": "2026-01-01",
  "occurred_at": "2026-01-15T17:04:12Z",
  "payload": {
    "id": 1234
  }
}

What a New Version Changes​

Publishing a new payload version does not immediately change what an existing subscription receives. A subscription pinned to an earlier date keeps getting the payloads of its own version, with the same fields in the same shape. So a new version will not break your handler the day it ships, and equally you do not pick up new fields automatically.

Version Retirement​

That grace period is not indefinite. Old payload versions are eventually retired, and migrating is not optional.

Clio gives at least 90 days' notice in the product's API changelog before a version stops being supported, including what changed and how to migrate. Once that period ends, a retired version can no longer be chosen as a pin, and subscriptions still pinned to the retired version are moved forward to the next one. A handler that has not been updated by then starts receiving a payload it was not written for.

Treat the date in the changelog as a deadline rather than a suggestion, and migrate before it.

Migrating to a Newer Version​

Move a subscription forward by making a PATCH request to /webhook_subscriptions/{id} with a later published version, for example:

{
  "schema_version": "2026-06-01"
}

Changing the pin does not change the subscription's status, and no new challenge is issued. The next delivery uses the new pin.

A safe way to migrate:

  1. Check the API reference for the payload version you intend to move to, and compare it against what you currently receive.
  2. Update your handler so it accepts both the current and new payload shapes. Tolerating both means the switch does not have to be instantaneous.
  3. Deploy the handler.
  4. PATCH the subscription's schema_version forward.
  5. Confirm that incoming deliveries carry the new schema_version and the payload shape you expected.

These steps do not have to happen all at once, but complete them before the retirement date published in the changelog. After that date the pin is moved forward for you, and a handler that is not ready receives the new payload regardless.

Migrate forward, not back

Setting schema_version to an earlier published version is allowed, but any fields your handler came to rely on from the newer version will stop arriving. Treat a rollback as a change that needs the same care as a migration.

Published Versions​

Only one payload version has been published so far, 2026-01-01, and it is currently the only value schema_version accepts. The API reference documents the fields for each event.