Skip to main content

Webhook versioning

The structure of the payload object sent in a webhook depends on the value of the Payload Version option chosen when creating the webhook.

Pinned vs latest versioning​

  • Pinned version: For webhooks with Payload Version set to "Pinned", payload objects will use the pinned API version in your account settings at the time the webhook is triggered. For example, if your account is pinned to version 5.10.0, even if you change the API version for a specific request via versioning, the payload object will still be based upon the 5.10.0 version.

  • Latest version: If the webhook is created with Payload Version set to "Latest", payload objects will always use the latest version available at the time the webhook is triggered.

For production sites, all webhooks should be created with Payload Version set to "Pinned". This ensures consistent payload structure. When you're ready to upgrade, you can change the pinned API version in your account, and webhook payloads will automatically start using the new pinned version.

Testing version upgrades​

To test upgrades before applying them to production:

  1. Create a new webhook with Payload Version set to "Latest"
  2. Configure it to listen to events from a test site
  3. Verify your endpoints can correctly handle the new version of payload objects
caution

Using the latest API version ties the webhook to whichever is the current latest version. We don't recommend using this setting in production, as the payload object may change with every upgrade and break your integration. Instead, rely on the pinned API version, which only upgrades when you change your account's pinned API version.

Note that webhook payloads cannot be changed once created. If you retry old webhook deliveries, they will use the structure of the payload at the time of creation.