Getting Started with Webhooks

Webhooks is a delivery mechanism that allow you to subscribe to notifications that occur within a Benchling tenant. Webhooks are distinct from the Amazon Eventbridge connection, though both can deliver events; check out our Getting Started with Events guide for more details. Webhooks currently support the delivery of Events and App Signals:

• Events are a class of webhook made up of data events that correspond to actions or changes within Benchling. This includes examples like entity registration and workflow task updates.
• App Signals are a class of webhook made up of notifications that correspond to actions or changes that occur related to Benchling Apps. This includes examples like app installation, as well as user app canvas interaction. These

The full list of existing webhook schemas can be found in the Webhook Reference; additionally, currently supported data events that appear in the Events Reference are also available for delivery via webhook.

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

Subscribing to Webhooks

To start receiving webhooks, an app must subscribe to the webhook type(s) that it cares about. These webhook subscriptions are included in the app's manifest, like the following example:

manifestVersion: 1
info:
  name: Example App
  version: 0.0.1
features:
  - name: Example Feature
    id: example_feature
    type: ASSAY_RUN
subscriptions:
  deliveryMethod: WEBHOOK
  messages:
    - type: v2.canvas.userInteracted
    - type: v2.canvas.initialized

Once the app has been created/updated with the relevant webhook subscriptions, a publicly available HTTPS endpoint can be provided in the webhook URL field from the Developer Console:

🚧

Where is webhookUrl?

Legacy apps included the webhookUrl field in their manifest; this is no longer supported for Sharable Apps. Instead, Sharable Apps manage their webhook URL from the Developer Console as described above. Check out the Shareable Apps FAQ for more details.

Different classes of notification are sent to different subpaths of the app’s webhookUrl; app lifecycle webhooks are sent to the /lifecycle subpath, while canvas interaction webhooks and event webhooks are sent to the /canvas and /event subpaths, respectively.

For example, when installing the app from the previous screenshot would result in a v2.app.installed webhook being sent to https://poetic-mildly-bear.ngrok.free.app/1/webhook/lifecycle; the webhook body would look like the following:

{
  "version": "0",
  "baseURL": "https://example.benchling.com",
  "tenantId": "ten_XXXXXXXXXX",
  "app": {
    "id": "app_XXXXXXXXXXXXXXXX"
  },
  "appDefinition": {
    "id": "appdef_XXXXXXXXXX",
    "versionNumber": "0.0.1"
  },
  "channel": "app_signals",
  "message": {
    "type": "v2.app.installed",
    "deprecated": false
  }
}