Receiving Events in Your App

Benchling's event system lets your app react to actions and changes within a tenant without polling the API. When something happens in Benchling — an entity is registered, a workflow task is updated, a request is created — an event is emitted and delivered directly to your app.

Common use cases:

• Triggering downstream object creation when a workflow step completes
• Syncing changes to an external database or LIMS in real time
• Sending notifications to Slack, Teams, or other third-party tools
• Automating instrument interactions based on sample state changes

Best practice: Event payloads should not be treated as fully up-to-date. Events can be delivered late or out of order. Use the apiURL field in the payload to fetch the current state of the resource via the REST API when accuracy matters.

Choosing a Delivery Method

Benchling supports two ways to deliver events to your app: Webhooks and AWS EventBridge. For most integrations, Webhooks is the right choice.

Choose Webhooks if you are:

• Building a new integration from scratch
• Using App Signals (canvas interactions, app lifecycle events)
• Looking for the simplest setup and fastest access to new event types

Choose EventBridge if you are:

• Working within an existing AWS EventBridge infrastructure
• Specifically need hydrated payloads without a follow-up API call
• Subscribing to alpha or beta events not yet available via webhooks

Receiving Events via Webhooks

Two things are required:

• A Benchling App with event subscriptions declared in the App Manifest
• A publicly available HTTPS endpoint to receive webhook POST requests

1. Add subscriptions to your App Manifest

Declare the event types your app should receive in the subscriptions block:

manifestVersion: 1
info:
  name: My Integration
  version: 1.0.0
subscriptions:
  deliveryMethod: WEBHOOK
  messages:
    - type: v2.entity.registered
    - type: v2.workflowTask.updated
    - type: v2.request.created

The full list of subscribable event types is in the Webhooks Reference.

2. Set your webhook URL in the Developer Console

After installing or updating your app, set your HTTPS endpoint in the Developer Console. Benchling routes different event classes to subpaths of that URL automatically:

• App lifecycle events → /lifecycle
• Canvas interaction events → /canvas
• Data events → /event

For a complete walkthrough including payload handling and signature verification, see Getting Started with Webhooks.

Receiving Events via EventBridge

Before you begin: EventBridge setup requires Tenant Admin access with the Developer Platform capability enabled, and an active AWS account. If you're starting a new integration, Webhooks is recommended.

1. Create a subscription in Benchling

Navigate to https://<YOUR_TENANT>.benchling.com/event-subscriptions (or Feature Settings → Developer Console → Events) and create a new subscription with your AWS Account ID, region, and event bus name. This creates a Partner Event Source in your AWS account.

⚠️

Act immediately. AWS automatically deletes a Partner Event Source if it isn't associated with an event bus. Complete Step 2 before leaving the AWS console.

2. Associate the source with an event bus

In the AWS EventBridge console, find the new Partner Event Source and associate it with a new event bus. Each Benchling subscription maps 1:1 to a bus — this keeps events from dev, test, and prod environments isolated.

3. Create rules and targets

Create an EventBridge rule on your bus to route events to a target (Lambda, SQS, SNS, etc.), filtering by event type using the detail-type field:

{
  "detail-type": ["v2.entity.registered"]
}

For detailed rule configuration, filtering patterns, and CloudFormation/SAM templates, see the Events Getting Started guide.

What's Next

• Getting Started with Webhooks — complete webhook setup and security verification
• Getting Started with Events — full EventBridge configuration walkthrough
• Webhooks Reference — all webhook-available events and payload schemas
• Events Reference — all EventBridge-available events
• Events FAQs — delivery guarantees, recovery procedures, common questions