Skip to navigation

Getting Started with Webhooks

Learn how to configure Benchling webhooks and receive webhook payloads in your integration. This guide covers webhook setup, request handling, and the basic lifecycle of webhook delivery.

Webhooks are a delivery mechanism that allows 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.

Use the Events Reference when you need EventBridge payload details or a delivery-model comparison.

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, listed in the API Reference for V2 and V3. 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:

The webhook URL field on an app's page in the Developer Console

Where is webhookUrl?

Legacy apps included the webhookUrl field in their manifest; this is no longer supported for Shareable Apps. Instead, Shareable 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, 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
}
}

After the webhook arrives

Once delivery is working, the next steps are usually:

  1. Verify the delivery with Webhook Security before trusting the payload.
  2. Fetch the latest resource state from the REST API Reference before mutating data or syncing another system.