{"id":29053397,"url":"https://github.com/quiltdata/benchling-webhook","last_synced_at":"2026-04-14T04:03:56.466Z","repository":{"id":294340244,"uuid":"940328347","full_name":"quiltdata/benchling-webhook","owner":"quiltdata","description":"API Gateway for processing Benchling Events","archived":false,"fork":false,"pushed_at":"2026-04-08T16:12:46.000Z","size":5790,"stargazers_count":1,"open_issues_count":10,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T16:27:16.139Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quiltdata.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-02-28T01:42:44.000Z","updated_at":"2026-04-08T14:43:21.000Z","dependencies_parsed_at":"2026-01-16T23:06:39.442Z","dependency_job_id":null,"html_url":"https://github.com/quiltdata/benchling-webhook","commit_stats":null,"previous_names":["quiltdata/benchling-webhook"],"tags_count":157,"template":false,"template_full_name":null,"purl":"pkg:github/quiltdata/benchling-webhook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiltdata%2Fbenchling-webhook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiltdata%2Fbenchling-webhook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiltdata%2Fbenchling-webhook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiltdata%2Fbenchling-webhook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quiltdata","download_url":"https://codeload.github.com/quiltdata/benchling-webhook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiltdata%2Fbenchling-webhook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31781292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-27T01:05:41.338Z","updated_at":"2026-04-14T04:03:56.460Z","avatar_url":"https://github.com/quiltdata.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Benchling Webhook Integration for Quilt\n\nThe Benchling Webhook creates a seamless connection between [Benchling](https://www.benchling.com)'s Electronic Lab Notebook (ELN) and [Quilt](https://www.quilt.bio)'s Scientific Data Managements System (SDMS) for Amazon S3.\nIt not only allows you to view Benchling metadata and attachments inside Quilt packages, but also enables users to browse Quilt package descriptions from inside Benchling notebookes.\n\nThe webhook works through a [Benchling App](https://docs.benchling.com/docs/getting-started-benchling-apps) that must be installed in your Organization by a Benchling Administrator and configured to call your stack's unique webhook (see Installation, below).\n\n## Availability\n\nIt is available in the Quilt Platform (1.65 or later) or as a standalone CDK stack via the `@quiltdata/benchling-webhook` [npm package](https://www.npmjs.com/package/@quiltdata/benchling-webhook).\n\n## Functionality\n\n### Auto-Packaging\n\n![Packaged Notebook](imgs/benchling-package.png)\n\nWhen scientists create notebook entries in Benchling, this webhook automatically:\n\n- **Creates a dedicated Quilt package** for each notebook entry\n- **Synchronizes metadata** from Benchling (experiment IDs, authors, etc.) into that package\n- **Copies attachments** from that notebook into Amazon S3 as part of the package.\n- **Enables orgnizational data discovery** by making contents available in ElasticSearch, and metadata available in Amazon Athena.\n\n### Package Linking\n\n![experiment_id](imgs/benchling-link.png)\n\nIn addition, Quilt users can 'tag' additional packages by setting the `experiment_id` (or a custom metadta key) to the display ID of a Benchling notebook, e.g., `EXP00001234`.\n\nFrom inside the Quilt Catalog:\n\n1. Navigate to the package of interest\n2. Click 'Revise Package'\n3. Go the metadata editor in the bottom left\n4. In the bottom row, enter `experiment_id` as key and the display ID as the value.\n5. Set the commit message and click 'Save'\n\n### Benchling App Canvas\n\n![App Canvas - Home](imgs/benchling-canvas.png)\n\nThe webhook includes a Benchling App Canvas, which allows Benchling users to view, browse, and sync the associated Quilt packages.\n\n- Clicking the package name opens it in the Quilt Catalog\n- The `sync` button will open the package or file in [QuiltSync](https://www.quilt.bio/quiltsync), if you have it installed.\n- The `Update` button refreshes the package, as Benchling only notifies Quilt of changes when the metadata fields are modified.\n\nThe canvas also allows you to browse package contents:\n\n![App Canvas - Browse](imgs/benchling-browse.png)\n\nand view package metadata:\n\n![App Canvas - Metadata](imgs/benchling-browse.png)\n\n#### Inserting a Canvas\n\nIf the App Canvas is not already part of your standard notebook template, Benchling users can add it themselves:\n\n1. Create a notebook entry\n2. Select \"Insert\" → \"Canvas\"\n3. Choose \"Quilt Package\"\n4. After it is inserted, click the \"Create\" button\n\n![App Canvas - Insert](imgs/benchling-insert.png)\n\n### Security Features\n\n**Single Authentication Layer:**\n\n- **FastAPI HMAC Verification** - All webhook requests verified against Benchling secret\n- Signatures computed over raw request body\n- Invalid signatures return 403 Forbidden\n\n**Optional Network Filtering:**\n\n- **Resource Policy IP Filtering** - Free alternative to AWS WAF ($7/month saved)\n- Blocks unknown IPs at API Gateway edge (applies to all endpoints)\n- **BREAKING CHANGE (v1.1.0+)**: Health endpoints NO LONGER exempt from IP filtering\n- External monitoring services must be added to allowlist or IP filtering disabled\n- NLB health checks unaffected (bypass API Gateway)\n- IP filtering does NOT replace authentication (it's defense-in-depth)\n\n**Infrastructure Security:**\n\n- Private network (ECS in private subnets, no public IPs)\n- VPC Link encrypted connection between API Gateway and NLB\n- TLS 1.2+ encryption on all API Gateway endpoints\n- CloudWatch audit trail for HMAC verification and resource policy decisions\n- Least-privilege IAM roles\n\n## Installation\n\n### 1. Installing the Benchling App\n\nThis requires a Benchling admin to use `npx` from [NodeJS](https://nodejs.org) version 18 or later.\n\n#### 1.1 Get the app manifest\n\nDownload `app-manifest.yaml` from the\n[latest GitHub release](https://github.com/quiltdata/benchling-webhook/releases/latest),\nor generate one locally:\n\n```bash\nnpx @quiltdata/benchling-webhook@latest manifest\n```\n\n#### 1.2 Upload the manifest to Benchling\n\n- Follow Benchling's [create](https://docs.benchling.com/docs/getting-started-benchling-apps#creating-an-app-from-a-manifest) and [install](https://docs.benchling.com/docs/getting-started-benchling-apps#installing-your-app) instructions.\n- Save the **App Definition ID**, **Client ID**, and **Client Secret** for the next step.\n\n### 2. Configuring the Benchling App\n\nYour command-line environment must have AWS credentials for the account containing your Quilt stack.\nAll you need to do is use `npx` to run the package:\n\n```bash\nnpx @quiltdata/benchling-webhook@latest\n```\n\nIf you need to choose AWS credentials explicitly, prefer `--aws-profile`:\n\n```bash\nnpx @quiltdata/benchling-webhook@latest --aws-profile myaws\n```\n\nYou can also use `AWS_PROFILE`:\n\n```bash\nAWS_PROFILE=myaws npx @quiltdata/benchling-webhook@latest\n```\n\n`--profile` is different: it selects a local `benchling-webhook` config profile under `~/.config/benchling-webhook/`, not your AWS credential profile.\n\nThe wizard will guide you through:\n\n1. **Catalog discovery** - Detect your Quilt catalog configuration\n2. **Stack validation** - Extract settings from your CloudFormation stack\n3. **Credential collection** - Enter Benchling app credentials\n4. **Package settings** - Configure bucket, metadata key, and optional Quilt workflow\n5. **Deployment mode selection**:\n   - **Integrated**: Uses your Quilt stack's built-in webhook, if any\n   - **Standalone**: Deploys a separate webhook stack for testing\n\n**Note**: Configuration is stored in `~/.config/benchling-webhook/` using the [XDG Base Directory](https://wiki.archlinux.org/title/XDG_Base_Directory) standard, supporting multiple profiles.\n\n### 3. Configure Webhook URL\n\nAdd the webhook URL (displayed after setup) to your [Benchling app settings](https://docs.benchling.com/docs/getting-started-benchling-apps#installing-your-app).\n\n**Important**: The endpoint URL format is `https://{api-id}.execute-api.{region}.amazonaws.com/{stage}/webhook` (includes stage prefix like `/prod/webhook` or `/dev/webhook`).\n\nIf your integration reads or writes within a specific Benchling project, share that project with the service account behind the Benchling App Client ID. This integration uses the app/service-account identity, not an end-user OAuth session. If project access appears broken, verify the service account can perform a simple read or list API call for the target project.\n\n### 4. Test Integration\n\nIn Benchling:\n\n1. Create a notebook entry\n2. Insert Canvas → Select \"Quilt Package\"\n3. Click \"Create\"\n\nA Quilt package will be automatically created and linked to your notebook entry.\nIf you run into problems, contact [Quilt Support](support@quilt.bio)\n\n## Multi-Stack Deployments (v0.9.8+)\n\nStarting with version 0.9.8, you can deploy **multiple webhook stacks** in the same AWS account/region. This is useful for:\n\n- **Multi-tenant deployments** - Separate stacks for each customer\n- **Environment isolation** - Dev, staging, prod in same account\n- **A/B testing** - Parallel stacks with different configurations\n\n### Profile-Based Stack Names\n\nEach profile automatically gets its own CloudFormation stack:\n\n```bash\n# Default profile uses legacy name (backwards compatible)\nnpx @quiltdata/benchling-webhook@latest deploy --profile default\n# Creates: BenchlingWebhookStack\n\n# Other profiles get unique names\nnpx @quiltdata/benchling-webhook@latest deploy --profile sales\n# Creates: BenchlingWebhookStack-sales\n\nnpx @quiltdata/benchling-webhook@latest deploy --profile customer-acme\n# Creates: BenchlingWebhookStack-customer-acme\n```\n\n### Custom Stack Names\n\nYou can also specify a custom stack name in your profile configuration:\n\n```json\n{\n  \"deployment\": {\n    \"stackName\": \"MyCustomWebhookStack\",\n    ...\n  }\n}\n```\n\n### Managing Multiple Stacks\n\nAll commands support the `--profile` flag:\n\n```bash\n# Deploy a specific profile\nnpx @quiltdata/benchling-webhook@latest deploy --profile sales\n\n# Check status\nnpx @quiltdata/benchling-webhook@latest status --profile sales\n\n# View logs\nnpx @quiltdata/benchling-webhook@latest logs --profile sales\n\n# Destroy stack\nnpx @quiltdata/benchling-webhook@latest destroy --profile sales\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquiltdata%2Fbenchling-webhook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquiltdata%2Fbenchling-webhook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquiltdata%2Fbenchling-webhook/lists"}