Getting Started with Webhooks

Webhooks is a delivery mechanism that allow you to subscribe to notifications that occur within a Benchling tenant, similar to the Events product. Webhooks are distinct from Events, however: Creation, registration, and completion notifications are not supported by webhooks. Webhooks support is currently limited to App Signals notifications.

App Signals is a class of webhook made up of notifications that correspond to actions or changes that occur with Benchling Apps. This class includes App Lifecycle notifications, like when an app is installed or uninstalled, as well as App Interaction notifications, like when a user interacts with an app canvas.

Subscribing to webhooks requires you to configure the following for your app:

An App Manifest to install your app to a Benchling tenant
A publicly available HTTPS endpoint that can receive the webhook requests

App Lifecycle Webhooks

To start receiving App Lifecycle webhooks, your app manifest must include the lifecycleManagement and webhookUrl field. lifecycleManagement must be AUTOMATIC, and webhookUrl must be a publicly available HTTPS endpoint. This is the base URL where the app will receive all webhook notifications from Benchling. When these fields are defined in the manifest, your app will automatically be subscribed to App Lifecycle notifications:

manifestVersion: 1
info:
  name: Example App
  description: Hello World description
settings:
  lifecycleManagement: AUTOMATIC
  webhookUrl: https://o2vzytebzbkxhdk6de6x4je0qekea.lambda-url.eu-north-1.on.aws/

Different classes of notification are sent to different subpaths of the app’s webhookUrl; App Lifecycle notifications are sent to the /lifecycle subpath. For example, installing an app from the following manifest would result in an v0-beta.app.installed webhook being sent to https://webhook.site/8c5d5825-ef95-4149-a4e0-12bad7be98d2/lifecycle, like the following example:

{
  "app": {
    "id": "app_XXXXXXXXXXXXXXXX"
  },
  "baseURL": "tenant.benchling.com",
  "channel": "app_signals",
  "message": {
    "clientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "clientSecret": "XXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXX",
    "deprecated": false,
    "excludedProperties": [],
    "type": "v0-beta.lifecycle.activateRequested"
  },
  "tenantId": "ten_XXXXXXXXXX",
  "version": "0"
}

App Interaction Webhooks

To start receiving App Interaction webhooks, your app manifest must also implement at least one feature. Features are extension points in the Benchling UI that allow your app to interact directly with users. Using our previous example, we can update the manifest to implement an APP_HOMEPAGE feature which gives your app permissions to create an interactive experience on the app homepage:

manifestVersion: 2
info:
  name: Example App
  description: Hello World description
settings:
  lifecycleManagement: AUTOMATIC
  webhookUrl: https://o2vzytebzbkxhdk6de6x4je0qekea.lambda-url.eu-north-1.on.aws/
features:
- name: My App Feature
  id: test_feature
  type: APP_HOMEPAGE

With a feature now defined in the app manifest, your app is now subscribed to App Interaction webhooks related to that feature. App Interaction notifications are sent to the /canvas subpath; for example, a user interacting with a canvas on the app’s homepage would result in a v0-alpha.canvas.userInteracted webhook being sent to `https://o2vzytebzbkxhdk6de6x4je0qekea.lambda-url.eu-north-1.on.aws/canvas, like the following example:

{
   "version": "0",
   "baseURL": "tenant.benchling.com",
   "tenantId": "ten_foo",
   "appId": "app_bar",
   "channel": "app_signals",
   "message": {
     "buttonId": "search_button",
     "canvasId": "cnvs_1234abcd",
     "type": "v0.canvas.userInteracted",
     "deprecated": false,
     "excludedProperties": []
   },
}