Webhook Versioning

Webhook users can select the desired webhook version for each webhook receiver URL, and the specific version of the webhook payload will be sent to the receiving URL accordingly.

This versioning mechanism helps webhook users to concurrently test multiple webhook versions, facilitating a seamless transition during webhook migration.

You can pick from any of the available webhook versions for each webhook URL. Simply navigate to the webhook URL configuration screen in the admin.aftership.com web portal, as shown below:


To ensure a smooth transition, you can test the new version by adding another webhook URL and selecting the desired version for testing purposes.

It's important to note that your selected webhook version operates independently of the API version you're using. For instance, you can specify 2024-01 in the API request URL, while continuing to use 2023-10 for the selected webhook version within the admin portals.

as-webhook-version request header is included in every webhook request to indicate the payload version.

Header NameDescriptionFormat
as-webhook-versionSelected webhook version.YYYY-MM

2023-10 2024-01 2024-04 2024-07 and so on.

The lifecycle of a webhook version aligns with the corresponding API version, including both its initiation and end-of-support dates. When a selected webhook version reaches its end-of-life, AfterShip will update it to the oldest supported version automatically. Consequently, the deprecated version will no longer be available for selection.