> This page is for Developer Documentation. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.benchling.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server. # Events Reference Benchling delivers events two ways, and they do not share the same payload shape, permissions model, or subscription path. Use this page when you need EventBridge payload details, supported event types, or the differences between the two delivery models. For the HTTP message contract Benchling sends to a webhook receiver, see [Getting Started with Webhooks](/docs/getting-started-with-webhooks) and [Webhook Security](/docs/webhook-verification). Once a delivery arrives and you need the latest resource state, use the [REST API Reference](/docs/api). ## JSON example pages * [V2 EventBridge JSON Examples](/docs/events-reference-v2-examples) * [V2 Beta EventBridge JSON Examples](/docs/events-reference-v2-beta-examples) * [V2 Alpha EventBridge JSON Examples](/docs/events-reference-v2-alpha-examples) ## Delivery model differences | Need | Webhooks | EventBridge | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | Delivery target | HTTPS endpoint configured for your app | AWS event bus configured in your AWS account | | Typical use case | App-driven integrations and direct handlers | AWS-native routing, rules, and multiple downstream targets | | Payload shape | Thin webhook message with event metadata and IDs | Hydrated Benchling payload shaped like the related API resource | | Permissions model | Inherits app permissions | Not permissioned | | Best next step | Review [Getting Started with Webhooks](/docs/getting-started-with-webhooks) and [Webhook Security](/docs/webhook-verification) | Review the payload details and event tables below | ## EventBridge payload reference All events have a standard JSON payload with the following structure: ```javascript { "version": "0", // Unused "id": "XXXX-XXXX-...", // Unique AWS ID "detail-type": "v2.request.created", // .. "source": "aws.partner...", // Event Subscription Name "account": 123123123123, // AWS Destination Account ID "time": "2015-06-14T22:26:59.673559+00:00", // Isoformat UTC when the event is created "region": "us-west-1", // AWS region "resources": [], // Unused "detail": { "createdAt": "2015-06-14T22:26:59.673559+00:00", // Isoformat UTC when the event is created, same as "time" above "deprecated": false, // True if an event has been deprecated. It is best practice to alert on this to know when to migrate. "entry": {}, // This will vary, depending on resource type "eventType": "v2.request.created", // .., same as "detail-type" above "excludedProperties": ["dropped_key1", "dropped_key2"], // Empty unless properties were excluded for being too large "id": "evt_XXX...", // Unique Benchling Event ID "schema": { "name": "...", // Name of the schema event is related to "id": "..." // id of the schema event is related to }, "updates": ["fields.cool"] // Fields that changed. Only present on update events } } ``` In the above, the `"entry": {...}` field will vary based on the resource that's being sent. See the "Resource Name" column in the [V2 Events Reference section](#v2-events-reference) for the field name for each event and the "API Get Endpoint Link" column for a link to the API reference documentation that outlines the content. > **Warning** > > ### Outdated Event Payloads > > Data in the event payload should **not** be treated as up-to-date. Events can be delivered late or out-of-order, so it's best practice to look up the corresponding objects with the Benchling API if you need the latest information. ## Oversized Events Due to the fact that events on EventBridge have a maximum size of 256kb, **some fields will be dropped when the event is oversized**. The properties that were dropped are included in the `excludedProperties` field. If one of those fields is critical for you to retrieve, the resource object (`entry: {...}` in the above example) has a `apiURL` field that contains the URL to retrieve the full resource from the API. ## Event Subscription To subscribe to any of the following events, you'll need to follow the instructions in the [Getting Started Guide](/docs/events-getting-started#setting-up-a-subscription) and add that event type from the dropdown. ## V2 Events Reference | Event Name | Event Description | Resource Name | API Get Endpoint Link | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- | | `v2.assayRun.created` | Fired when a run is created | `assayRun` | [Assay Run](/docs/api/v2/benchling-api/assay-runs/get-assay-run) | | `v2.assayRun.updated.fields` | Fired when a run's fields are updated | `assayRun` | [Assay Run](/docs/api/v2/benchling-api/assay-runs/get-assay-run) | | `v2.automationFileTransform.updated.status.running` | Fired when an automation file transform changes to `running` status | `automationFileTransform` | [Automation File Transform](/docs/api/v2/benchling-api/lab-automation/get-lab-automation-transform) | | `v2.automationFileTransform.updated.status.pending` | Fired when an automation file transform changes to `pending` status | `automationFileTransform` | [Automation File Transform](/docs/api/v2/benchling-api/lab-automation/get-lab-automation-transform) | | `v2.automationFileTransform.updated.status.succeeded` | Fired when an automation file transform changes to `succeeded` status | `automationFileTransform` | [Automation File Transform](/docs/api/v2/benchling-api/lab-automation/get-lab-automation-transform) | | `v2.automationFileTransform.updated.status.failed` | Fired when an automation file transform changes to `failed` status | `automationFileTransform` | [Automation File Transform](/docs/api/v2/benchling-api/lab-automation/get-lab-automation-transform) | | `v2.entity.registered` | Fired when an entity is registered | `entity` | [Entity Resource](/docs/events-reference-v2-examples#v2entityregistered) | | `v2.entry.created` | Fired when a notebook entry is created. Only applicable for entries that are not a part of a Legacy Workflow. | `entry` | [Entry Resource](/docs/api/v2/benchling-api/entries/get-entry) | | `v2.entry.updated.fields` | Fired when a notebook entry's schema or fields are updated. Only applicable for entries that are not a part of a Legacy Workflow. | `entry` | [Entry](/docs/api/v2/benchling-api/entries/get-entry) | | `v2.entry.updated.reviewRecord` | Fired when a notebook entry's reviewRecord is updated. Only applicable for entries that are not a part of a Legacy Workflow. Not applicable as of yet for the new review process. | `entry` | [Entry](/docs/api/v2/benchling-api/entries/get-entry) | | `v2.request.created` | Fired when a request is created | `request` | [Request](/docs/api/v2/benchling-api/legacy-requests/get-request) | | `v2.request.updated.fields` | Fired when a request's fields are updated | `request` | [Request](/docs/api/v2/benchling-api/legacy-requests/get-request) | | `v2.request.updated.status` | Fired when a request's status is updated | `request` | [Request](/docs/api/v2/benchling-api/legacy-requests/get-request) | | `v2.workflowTaskGroup.created` | Fired when a workflow task group is created | `workflowTaskGroup` | [Workflow Task Group](/docs/api/v2/benchling-api/workflow-task-groups/get-workflow-task-group) | | `v2.workflowTaskGroup.mappingCompleted` | Fired when a workflow task group completes a batch of mappings. Can fire more than once per task group | `workflowTaskGroup` | [Workflow Task Group](/docs/api/v2/benchling-api/workflow-task-groups/get-workflow-task-group) | | `v2.workflowTaskGroup.updated.watchers` | Fired when a workflow task group's watchers are updated | `workflowTaskGroup` | [Workflow Task Group](/docs/api/v2/benchling-api/workflow-task-groups/get-workflow-task-group) | | `v2.workflowTask.created` | Fired when a workflow task is created | `workflowTask` | [Workflow Task](/docs/api/v2/benchling-api/workflow-tasks/get-workflow-task) | | `v2.workflowTask.updated.assignee` | Fired when a workflow task's assignee is updated | `workflowTask` | [Workflow Task](/docs/api/v2/benchling-api/workflow-tasks/get-workflow-task) | | `v2.workflowTask.updated.scheduledOn` | Fired when a workflow task's scheduledOn is updated | `workflowTask` | [Workflow Task](/docs/api/v2/benchling-api/workflow-tasks/get-workflow-task) | | `v2.workflowTask.updated.status` | Fired when a workflow task's status is updated | `workflowTask` | [Workflow Task](/docs/api/v2/benchling-api/workflow-tasks/get-workflow-task) | | `v2.workflowTask.updated.fields` | Fired when a workflow task's fields are updated | `workflowTask` | [Workflow Task](/docs/api/v2/benchling-api/workflow-tasks/get-workflow-task) | | `v2.workflowOutput.created` | Fired when a workflow output is created | `workflowOutput` | [Workflow Output](/docs/api/v2/benchling-api/workflow-outputs/get-workflow-output) | | `v2.workflowOutput.updated.fields` | Fired when a workflow output's fields are updated | `workflowOutput` | [Workflow Output](/docs/api/v2/benchling-api/workflow-outputs/get-workflow-output) | ## V2 Beta Events Reference > **Warning** > > ### Using Beta Events > > Events under `v2-beta` are subject to more frequent breaking changes. We will notify developers prior to making breaking changes, but we recommend setting up monitoring to account for them if you are using them in production. Overall, we generally recommend only using `v2.*` events in production whenever possible. > > See our [Stability](/docs/stability) documentation for more information on Beta and what it means! Beta events are not listed by default. Please contact Benchling support to access these events. | Event Name | Event Description | Resource Name | API Get Endpoint Link | | ------------------------------------------------ | ---------------------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------- | | `v2-beta.automationInputGenerator.completed` | Fired when a file has been generated by an automation input generator | `automationInputGenerator` | [Automation Input Generator](/docs/api/v2/benchling-api/lab-automation/get-automation-input-generator) | | `v2-beta.automationOutputProcessor.completed` | Fired when a file has been processed by an automation output processor | `automationOutputProcessor` | [Automation Output Processor](/docs/api/v2/benchling-api/lab-automation/get-automation-output-processor) | | `v2-beta.automationOutputProcessor.uploaded` | Fired when a file has been uploaded to an automation output processor | `automationOutputProcessor` | [Automation Output Processor](/docs/api/v2/benchling-api/lab-automation/get-automation-output-processor) | | `v2-beta.automationFileTransform.updated.status` | Fired when a file transform undergoes a status change | `Transform` | [Transform](/docs/api/v2/benchling-api/lab-automation/get-lab-automation-transform) | ## V2 Alpha Events Reference > **Warning** > > ### Using Alpha Events > > Events under `v2-alpha` are in active development and can change or be removed entirely without notice. They should only be used for testing purposes and we encourage those that do use them to reach out with feedback! > > See our [Stability](/docs/stability) documentation for more information on Alpha and what it means! Alpha events are not listed by default. Please contact Benchling support to access these events. | Event Name | Event Description | Resource Name | API Get Endpoint Link | | ------------------------------------------ | -------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------ | | `v2-alpha.stageEntry.created` | Fired when a legacy workflow stage entry is created | `stageEntry` | [Stage Entry](/docs/api/benchling-api/stage-entry/get) | | `v2-alpha.stageEntry.updated.fields` | Fired when a legacy workflow stage entry's schema or fields are updated | `stageEntry` | [Stage Entry](/docs/api/benchling-api/stage-entry/get) | | `v2-alpha.stageEntry.updated.reviewRecord` | Fired when a legacy workflow stage entry's review record has transitioned status | `stageEntry` | [Stage Entry](/docs/api/benchling-api/stage-entry/get) |