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.