> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

## 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:

```yaml
---
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:

| Implicit Subscription Manifest field | Implicitly subscribed Webhook Types | Explicit Subscriptions                              |
| ------------------------------------ | ----------------------------------- | --------------------------------------------------- |
| App Feature                          | Canvas-related webhooks             | `v2.canvas.userInteracted`\ `v2.canvas.initialized` |
| App Configuration                    | App Configuration related webhooks  | `v2-beta.app.configuration.updated`                 |
| AUTOMATIC Lifecycle management       | Lifecycle webhooks                  | `v2.app.activateRequested`\ `v2.app.deactivated`    |

### 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 the`v0-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:

* **`lifecycleManagement`Sunset** - 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.activateRequested`Sunset** - 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](/docs/global-apps-faq) for more information, and reach out to your Benchling representative for early access to Shareable Apps.