Changelog

Explicit Webhook Subscriptions and Webhook Version Update

Existing webhook types are being promoted from v0 to v2, and a new explicit webhook subscription mechanism is being made generally available. These changes will go live on June 11th 2024. This date marks the start of a migration period, during which apps must be updated to support v2 webhooks and explicit webhook subscriptions. This migration period ends on July 11th 2024, at which time v0 webhooks and implicit webhook subscriptions will be fully sunset. Expand for more details.

What’s changing?

In anticipation of the release of Event delivery via webhook, a number of changes are being rolled out to existing webhooks. The two changes addressed here are the webhook message version increase, and the introduction of explicit webhook subscriptions:

Webhook Message Version

Benchling is incrementing the version number of existing webhook message types from v0 to v2 in order to align with the current version of Events. This involves some changes to the message version pattern:

• For most existing webhook types, this change only impacts the version number, while the other type fields remain the same.
  • For example, a webhook message with "type": "v0.canvas.userInteracted" will going forward be "type": "v2.canvas.userInteracted" instead.
• For existing lifecycle webhooks, this change is more substantial: The term lifecycle is being replaced with the term app to align with the existing structure of events.
  • For example, a webhook message with "type": "v0-beta.lifecycle.activateRequested" will going forward be "type": "v2.app.activateRequested" instead

Explicit Webhook Subscriptions

Previously, apps that included a webhookUrl field in their manifest were implicitly “subscribed” to a number of webhook message types based on the functionality they leveraged. For example, an app with a manifest that included app configuration options would be implicitly subscribed to all app config-related webhook messages. While simple, this dynamic meant app developers had little control over which webhook messages they received.

With the impending release of Events over Webhooks, Benchling is introducing a new system giving apps full control over their webhook subscriptions. This involves manifest fields that allow app developers to explicitly opt-in to specific webhook message types. Benchling will only send webhook messages that an app is explicitly subscribed to. Using the previous example, the same app will no longer be implicitly subscribed to these webhook messages; instead, the app can include the desired webhook messages in their webhook subscriptions.

An example of explicit subscriptions being used in an app manifest can be found below:

---
manifestVersion: 1
subscriptions:  
	deliveryMethod: WEBHOOK  
	messages:  
  	- type: v2.app.activateRequested
  	- type: v2.entry.created

Change management and migration

Given the impact of this breaking change to existing applications, Benchling has put in place measures to aid developers in this transition with zero-downtime:

• Double-sending - Benchling will send webhooks with the new v2 shapes in addition to the legacy v0 shapes. This means there will be two distinct webhooks corresponding to a single ‘event’ in Benchling. For any given webhook type, applications should process one or the other, but not both. This double-send behavior will stop on July 11th.
• Implicit subscription migration - Benchling will migrate the current “implicit” subscriptions an app has by converting them to “explicit” subscriptions in the manifest. This will impact the manifest version that exists in Benchling, but will not impact any app manifest saved locally or in source control. It is recommended that existing apps update these local manifest versions to include explicit webhook subscriptions. All apps must explicitly subscribe to any webhook types they require starting on July 11th.

The following list includes all existing implicit subscriptions, and what the corresponding explicit subscriptions look like:

When is this happening?

These changes are rolling out simultaneously on June 11th 2024., at which point apps must migrate. All apps must prepare to receive v2 webhook messages instead of the current v0. Existing apps will have their implicit subscriptions migrated automatically after this date. v0 webhooks and implicit webhook subscriptions will be fully sunset on July 11th 2024; at that point, all newly created apps must include webhook subscriptions explicitly in the manifest. Please reach out to your Benchling representative with any questions or concerns.

[SUNSET] App Lifecycle Management

The lifecycleManagement manifest field is being removed from the manifest specification, and the clientId and clientSecret fields in thev0-beta.lifecycle.activateRequested webhook type are being sunset. This webhook type will be replaced by the v2.app.activateRequested webhook type. Both of these are now considered deprecated, and will be fully sunset on July 11th 2024.

What’s changing?

As a part of the broader Shareable Apps rollout, the concept of app lifecycle management is being sunset. In service of this, the following changes are being made:

• lifecycleManagementSunset - The lifecycleManagement manifest field is being removed from the manifest specification, and will no longer be supported. This field previously determined whether an app was MANUAL or AUTOMATIC, and therefore how app developers received authentication credentials.
• v0-beta.lifecycle.activateRequestedSunset - In the same vein, the v0-beta.lifecycle.activateRequested webhook is being sunset. This webhook previously included the clientId and clientSecret values that allowed AUTOMATIC apps to complete the install process.

Going forward, Shareable Apps will no longer require the transfer of tenant-specific credentials. Instead, apps receive a single app-specific set of authentication credentials that they use to authenticate to all tenants. As such, neither the lifecycleManagement manifest field nor the v0-beta-lifecycle.activateRequested webhook are required for Shareable Apps.

When creating apps using a manifest, the lifecycleManagement field should be omitted. The v0-beta.lifecycle.activateRequested webhook is being replaced by the v2.app.activateRequested webhook for the purposes of automating app installation.

When is this happening?

These items are currently marked deprecated, and will be fully sunset on July 11th 2024. Existing Shareable Apps will not be impacted. Legacy apps that depend on the lifecycleManagement and/or the v0-beta.lifecycle.activate webhook must migrate to Shareable Apps before the sunset date to avoid interruption.

Check out the Shareable Apps FAQ for more information, and reach out to your Benchling representative for early access to Shareable Apps.