Benchling

Events Reference

Current Types of Events

Current events are linked to creation, registration, completion, and update of objects within Benchling. These are all the events that are available as part of the Beta. If you have additional Events that would be highly impactful, please reach out to Benchling support to let us know!

Event Payload

All events have a standard JSON payload with the following structure:

{
  "version": "0", # Unused
  "id": "XXXX-XXXX-...", # Unique AWS ID 
  "detail-type": "v2.request.created", # <version>.<resource_type>.<action>
  "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", # <version>.<resource_type>.<action>, 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 Events Reference section for the field name for each event and the "API Resource Link" column for a link to the content.

🚧

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 instruction in the Getting Started Guide and add that event type from the dropdown.

V2 Events Reference

Event Name

Event Description

Resource Name

API Resource Link

v2.assayRun.created

Fired when a run is created

assayRun

Run Resource

v2.assayRun.updated.fields

Fired when a run's fields are updated

assayRun

Run Resource

v2.entity.registered

Fired when an entity is registered

entity

Entity Resource

v2.entry.created

Fired when a notebook entry is created

entry

Entry Resource

v2.entry.updated.fields

Fired when a notebook entry's schema or fields are updated

entry

Entry Resource

v2.request.created

Fired when a request is created

request

Request Resource

v2.request.updated.fields

Fired when a request's fields are updated

request

Request Resource

JSON Examples

JSON Structure of all the V2 events.

v2.assayRun.created

{
  "version": "0",
  "id": "XXXX-XXXX-...", 
  "detail-type": "v2.assayRun.created",
  "source": "aws.partner...",
  "account": 123123123123,
  "time": "2015-06-14T22:26:59.673559+00:00", 
  "region": "us-west-1",
  "resources": [],
  "detail": {
    "createdAt": "2020-05-04T09:42:00+00:00",
    "deprecated": false,
    "excludedProperties": [
      "string"
    ],
    "id": "string",
    "schema": {
      "id": "string",
      "name": "string"
    },
    "assayRun": {
      "archiveRecord": {
        "reason": "string"
      },
      "createdAt": "string",
      "creator": {
        "handle": "string",
        "id": "string",
        "name": "string"
      },
      "entryId": "string",
      "fields": {
      },
      "id": "string",
      "isReviewed": true,
      "projectId": "string",
      "schema": {
        "id": "string",
        "name": "string"
      },
      "validationComment": "string",
      "validationSchema": "string",
      "apiURL": "string",
}
    },
    "eventType": "v2.assayRun.created"
  }
}

v2.assayRun.updated.fields

{
  "version": "0",
  "id": "XXXX-XXXX-...", 
  "detail-type": "v2.assayRun.updated.fields",
  "source": "aws.partner...",
  "account": 123123123123,
  "time": "2015-06-14T22:26:59.673559+00:00", 
  "region": "us-west-1",
  "resources": [],
  "detail": {
    "createdAt": "2020-05-04T09:42:00+00:00",
    "deprecated": false,
    "excludedProperties": [
      "string"
    ],
    "id": "string",
    "schema": {
      "id": "string",
      "name": "string"
    },
    "updates": [
      "string"
    ],
    "assayRun": {
      "archiveRecord": {
        "reason": "string"
      },
      "createdAt": "string",
      "creator": {
        "handle": "string",
        "id": "string",
        "name": "string"
      },
      "entryId": "string",
      "fields": {
      },
      "id": "string",
      "isReviewed": true,
      "projectId": "string",
      "schema": {
        "id": "string",
        "name": "string"
      },
      "validationComment": "string",
      "validationSchema": "string",
      "apiURL": "string",
    },
    "eventType": "v2.assayRun.updated.fields"
  }
}

v2.entity.registered

{
  "version": "0",
  "id": "XXXX-XXXX-...", 
  "detail-type": "v2.entity.registered",
  "source": "aws.partner...",
  "account": 123123123123,
  "time": "2015-06-14T22:26:59.673559+00:00", 
  "region": "us-west-1",
  "resources": [],
  "detail": {
    "createdAt": "2020-05-04T09:42:00+00:00",
    "deprecated": false,
    "excludedProperties": [
      "string"
    ],
    "id": "string",
    "schema": {
      "id": "string",
      "name": "string"
    },
    "entity": {
      "aliases": [
        "string"
      ],
      "archiveRecord": {
        "reason": "string"
      },
      "authors": [
        {
          "handle": "string",
          "id": "string",
          "name": "string"
        }
      ],
      "createdAt": "2020-05-04T09:42:00+00:00",
      "creator": {
        "handle": "string",
        "id": "string",
        "name": "string"
      },
      "customFields": {
      },
      "entityRegistryId": "string",
      "fields": {
      },
      "folderId": "string",
      "id": "string",
      "modifiedAt": "2020-05-04T09:42:00+00:00",
      "name": "string",
      "registryId": "string",
      "schema": {
        "id": "string",
        "name": "string"
      },
      "webURL": "string",
      "apiURL": "string",
    },
    "eventType": "v2.entity.registered"
  }
}

v2.entry.created

{
  "version": "0",
  "id": "XXXX-XXXX-...", 
  "detail-type": "v2.entry.created",
  "source": "aws.partner...",
  "account": 123123123123,
  "time": "2015-06-14T22:26:59.673559+00:00", 
  "region": "us-west-1",
  "resources": [],
  "detail": {
    "createdAt": "2020-05-04T09:42:00+00:00",
    "deprecated": false,
    "excludedProperties": [
      "string"
    ],
    "id": "string",
    "schema": {
      "id": "string",
      "name": "string"
    },
    "entry": {
      "archiveRecord": {
        "reason": "string"
      },
      "authors": [
        {
          "handle": "string",
          "id": "string",
          "name": "string"
        }
      ],
      "createdAt": "2020-05-04T09:42:00+00:00",
      "creator": {
        "handle": "string",
        "id": "string",
        "name": "string"
      },
      "customFields": {
      },
      "days": [
        {
          "date": "string",
          "notes": [
            {
              "checked": true,
              "externalFileId": "string",
              "indentation": 42,
              "links": [
                {
                  "id": "string",
                  "type": "link",
                  "webURL": "string"
                }
              ],
              "table": {
                "columnLabels": [
                  "string"
                ],
                "name": "string",
                "rows": [
                  {
                    "cells": [
                      {
                        "link": {
                          "id": "string",
                          "type": "link",
                          "webURL": "string"
                        },
                        "text": "string"
                      }
                    ]
                  }
                ]
              },
              "text": "string",
              "type": "text"
            }
          ]
        }
      ],
      "displayId": "string",
      "fields": {
      },
      "folderId": "string",
      "id": "string",
      "modifiedAt": "string",
      "name": "string",
      "reviewRecord": {
      },
      "schema": {
        "id": "string",
        "name": "string"
      },
      "webURL": "string",
      "apiURL": "string",
    },
    "eventType": "v2.entry.created"
  }
}

v2.entry.updated.fields

{
  "version": "0",
  "id": "XXXX-XXXX-...", 
  "detail-type": "v2.entry.updated.fields",
  "source": "aws.partner...",
  "account": 123123123123,
  "time": "2015-06-14T22:26:59.673559+00:00", 
  "region": "us-west-1",
  "resources": [],
  "detail": {
    "createdAt": "2020-05-04T09:42:00+00:00",
    "deprecated": false,
    "excludedProperties": [
      "string"
    ],
    "id": "string",
    "schema": {
      "id": "string",
      "name": "string"
    },
    "updates": [
      "string"
    ],
    "entry": {
      "archiveRecord": {
        "reason": "string"
      },
      "authors": [
        {
          "handle": "string",
          "id": "string",
          "name": "string"
        }
      ],
      "createdAt": "2020-05-04T09:42:00+00:00",
      "creator": {
        "handle": "string",
        "id": "string",
        "name": "string"
      },
      "customFields": {
      },
      "days": [
        {
          "date": "string",
          "notes": [
            {
              "checked": true,
              "externalFileId": "string",
              "indentation": 42,
              "links": [
                {
                  "id": "string",
                  "type": "link",
                  "webURL": "string"
                }
              ],
              "table": {
                "columnLabels": [
                  "string"
                ],
                "name": "string",
                "rows": [
                  {
                    "cells": [
                      {
                        "link": {
                          "id": "string",
                          "type": "link",
                          "webURL": "string"
                        },
                        "text": "string"
                      }
                    ]
                  }
                ]
              },
              "text": "string",
              "type": "text"
            }
          ]
        }
      ],
      "displayId": "string",
      "fields": {
      },
      "folderId": "string",
      "id": "string",
      "modifiedAt": "string",
      "name": "string",
      "reviewRecord": {
      },
      "schema": {
        "id": "string",
        "name": "string"
      },
      "webURL": "string",
      "apiURL": "string",
    },
    "eventType": "v2.entry.updated.fields"
  }
}

v2.request.created

{
  "version": "0",
  "id": "XXXX-XXXX-...", 
  "detail-type": "v2.request.created",
  "source": "aws.partner...",
  "account": 123123123123,
  "time": "2015-06-14T22:26:59.673559+00:00", 
  "region": "us-west-1",
  "resources": [],
  "detail": {
    "createdAt": "2020-05-04T09:42:00+00:00",
    "deprecated": false,
    "excludedProperties": [
      "string"
    ],
    "id": "string",
    "schema": {
      "id": "string",
      "name": "string"
    },
    "eventType": "v2.request.created",
    "request": {
      "assignees": [
        "string"
      ],
      "createdAt": "2017-04-23 01:30:50 +0000",
      "creator": {
        "handle": "string",
        "id": "string",
        "name": "string"
      },
      "displayId": "string",
      "fields": {
      },
      "id": "string",
      "projectId": "string",
      "requestStatus": "string",
      "requestor": {
        "handle": "string",
        "id": "string",
        "name": "string"
      },
      "scheduledOn": "2019-09-12",
      "schema": {
        "id": "string",
        "name": "string"
      },
      "webURL": "string",
      "apiURL": "string",
    }
  }
}

v2.request.updated.fields

{
  "version": "0",
  "id": "XXXX-XXXX-...", 
  "detail-type": "v2.request.updated.fields",
  "source": "aws.partner...",
  "account": 123123123123,
  "time": "2015-06-14T22:26:59.673559+00:00", 
  "region": "us-west-1",
  "resources": [],
  "detail": {
    "createdAt": "2020-05-04T09:42:00+00:00",
    "deprecated": false,
    "excludedProperties": [
      "string"
    ],
    "id": "string",
    "schema": {
      "id": "string",
      "name": "string"
    },
    "updates": [
      "string"
    ],
    "eventType": "v2.request.updated.fields",
    "request": {
      "assignees": [
        "string"
      ],
      "createdAt": "2017-04-23 01:30:50 +0000",
      "creator": {
        "handle": "string",
        "id": "string",
        "name": "string"
      },
      "displayId": "string",
      "fields": {
      },
      "id": "string",
      "projectId": "string",
      "requestStatus": "string",
      "requestor": {
        "handle": "string",
        "id": "string",
        "name": "string"
      },
      "scheduledOn": "2019-09-12",
      "schema": {
        "id": "string",
        "name": "string"
      },
      "webURL": "string",
      "apiURL": "string",
    }
  }
}

V2 Beta Events Reference

🚧

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.

Beta events are not listed by default. Please contact Benchling support to access these events.

πŸ“˜

Beta within a Beta

These are "beta" events within the events system's "beta" period. Longer term, the Events system will move out of "beta" and it will only be used on individual events.

Event Name

Event Description

Resource Name

API Resource Link

v2-beta.automation InputGenerator.completed

Fired when a file has been generated by an automation input generator

automation InputGenerator

Automation Input Generator Resource

v2-beta.automation OutputProcessor.completed

Fired when a file has been processed by an automation output processor

automation OutputProcessor

Automation Output Processor Resource

v2-beta.automation OutputProcessor.uploaded

Fired when a file has been uploaded to an automation output processor

automation OutputProcessor

Automation Output Processor Resource

JSON Examples

JSON structure of all V2 Beta events.

v2-beta.automationInputGenerator.completed

{
  "version": "0",
  "id": "XXXX-XXXX-...", 
  "detail-type": "v2-beta.automationInputGenerator.completed",
  "source": "aws.partner...",
  "account": 123123123123,
  "time": "2015-06-14T22:26:59.673559+00:00", 
  "region": "us-west-1",
  "resources": [],
  "detail": {
    "createdAt": "2020-05-04T09:42:00+00:00",
    "deprecated": false,
    "excludedProperties": [
      "string"
    ],
    "id": "string",
    "schema": {
      "id": "string",
      "name": "string"
    },
    "automationInputGenerator": {
      "assayRunId": "string",
      "automationFileConfig": {
        "name": "string"
      },
      "file": {
        "id": "string",
        "mimeType": "string",
        "name": "string",
        "type": "string",
        "uploadStatus": "string"
      },
      "id": "string",
      "status": "string"
    },
    "eventType": "v2-beta.automationInputGenerator.completed"
  }
}

v2-beta.automationOutputProcessor.completed

{
  "version": "0",
  "id": "XXXX-XXXX-...", 
  "detail-type": "v2-beta.automationOutputProcessor.completed",
  "source": "aws.partner...",
  "account": 123123123123,
  "time": "2015-06-14T22:26:59.673559+00:00", 
  "region": "us-west-1",
  "resources": [],
  "detail": {
    "createdAt": "2020-05-04T09:42:00+00:00",
    "deprecated": false,
    "excludedProperties": [
      "string"
    ],
    "id": "string",
    "schema": {
      "id": "string",
      "name": "string"
    },
    "automationOutputProcessor": {
      "assayRunId": "string",
      "automationFileConfig": {
        "name": "string"
      },
      "file": {
        "id": "string",
        "mimeType": "string",
        "name": "string",
        "type": "string",
        "uploadStatus": "string"
      },
      "id": "string",
      "status": "string"
    },
    "eventType": "v2-beta.automationOutputProcessor.completed"
  }
}

v2-beta.automationOutputProcessor.uploaded

{
  "version": "0",
  "id": "XXXX-XXXX-...", 
  "detail-type": "v2-beta.automationOutputProcessor.uploaded",
  "source": "aws.partner...",
  "account": 123123123123,
  "time": "2015-06-14T22:26:59.673559+00:00", 
  "region": "us-west-1",
  "resources": [],
  "detail": {
    "createdAt": "2020-05-04T09:42:00+00:00",
    "deprecated": false,
    "excludedProperties": [
      "string"
    ],
    "id": "string",
    "schema": {
      "id": "string",
      "name": "string"
    },
    "automationOutputProcessor": {
      "assayRunId": "string",
      "automationFileConfig": {
        "name": "string"
      },
      "file": {
        "id": "string",
        "mimeType": "string",
        "name": "string",
        "type": "string",
        "uploadStatus": "string"
      },
      "id": "string",
      "status": "string"
    },
    "eventType": "v2-beta.automationOutputProcessor.uploaded"
  }
}

V2 Alpha Events Reference

There are no events currently in v2-alpha.

❗️

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!

Updated 28 days ago

Events Reference


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.