Webhook Security
Use this page after Getting Started with Webhooks, once deliveries are arriving and before your handler trusts anything in them.
IP Allowlisting
We recommend only accepting incoming webhooks from an allowlisted IP address.
Benchling sends webhooks from a static range of IPs. Please reach out to your Benchling account team to get the IPs for your tenant.
Signature verification
Why Verify?
Subscribing to Benchling Webhooks requires hosting a publicly available endpoint to receive them. This introduces the potential for bad actors to attempt to impersonate Benchling or otherwise maliciously interact with the endpoint. To prevent this, Benchling includes a unique signature and timestamp with every webhook. By verifying this signature and timestamp, you can confirm the webhook was sent by Benchling.
For more information, check out the following resource: Introduction to Webhook Security on webhooks.fyi
Endpoint Signing Using JSON Web Key Sets
When your app is created in a tenant using the app manifest, Benchling creates an endpoint signing keypair (i.e. JWKS). Benchling generates webhook signatures using Elliptic Curve Signatures, which can be verified by your app using the JWKS published for your app. JWKS keysets can be obtained from a global endpoint using your app definition ID:
No {app_definition_id}?
If you don’t have access to the {app_definition_id}, you may be using Legacy Apps and need to use the legacy URL for your {app_installation_id}, like: https://benchling.com/apps/jwks/{app_installation_id}.
Your app should query the JWKS endpoint for the current values at intervals of no more than 6 hours, since Benchling frequently rotates these keypairs (and the corresponding public keys). Below is an example of a JWKS:
Do NOT hardcode the initial JWKS values!

Verifying Webhooks Manually
Benchling recommends using a package or library suitable for your language to verify the signature. Some common libraries are listed below in Sample Verification Libraries. The general steps required to verify a signature are outlined below; for a more detailed walkthrough with example Python code, check out the tutorial at the end of this guide.
Verify timestamp
The webhook-timestamp header includes a timestamp that corresponds to when Benchling attempted to send the webhook, used to prevent replay attacks. You should compare this timestamp against your system timestamp in UTC to make sure it’s within your tolerance; Benchling recommends using a 5 minute tolerance for this comparison.
Creating signed_content String
Each webhook includes three headers with additional information that are used for verification:
Webhook-Id: the unique message identifier for the webhook message. This identifier is unique across all messages, but will be the same when the same webhook is being resent (e.g. due to a previous failure).Webhook-Timestamp: timestamp in seconds since epoch.Webhook-Signature: the Base64 encoded list of signatures (space delimited).
The first verification step involves concatenating the webhook id, timestamp, and payload values, separated by the full-stop character (i.e. .). In code, it will look something like this (where body is the raw body of the request):
The signature is sensitive to any changes, so even a small change in the body will cause the signature to be completely different. This means that you should not alter the body in any way before verifying.
Getting webhook-signature
The webhook-signature header is composed of a list of signatures and their corresponding version identifiers, separated by a single space. Most often there is only a single signature, though due to keypair rotation there could be multiple signatures. It’s important to iterate through and attempt to validate each signature, since if any one of them is valid, the webhook is legitimate.
An example webhook-signature header may look like this:
These example signatures represent the following:
v1b: a raw ECDSA signature value, in big-endian orderv1bder: a DER encoded ECDSA signature valuev2bder: another DER encoded ECDSA signature value
Make sure to remove the version prefix and delimiter (e.g. v1b, or v1bder,) before verifying the signature.
The webhook signature header includes both raw ECDSA values (e.g. v1b) and DER encoded values (e.g. v1bder) for convenience; your choice of verification library will likely determine which signature encoding to use (see Sample Verification Libraries below). For the purposes of our example implementation, we’re using the DER encoded signature values.
Create public key and validate signature
You’ll need to convert the JWKS set queried from Benchling into a list of EllipticCurvePublicKeys which you can use to verify the signed_content. While the specifics will depend on your implementation, in code, this might look something like this:
With your public key in hand, you can iterate over the webhook signatures. Here, we’re working with the DER encoded signatures:
For a more in-depth example of this process, check out the tutorials below.
Sample Verification Libraries
Below are some common cryptographic libraries useful for verifying ECDSA signatures:
- Python: https://cryptography.io/en/latest/hazmat/primitives/asymmetric/ec/#elliptic-curve-signature-algorithms
- Node: https://nodejs.org/api/crypto.html
- Rust: https://docs.rs/signatory/latest/signatory/ecdsa/struct.Signature.html
- Ruby: https://ruby-doc.org/stdlib-3.1.2/libdoc/openssl/rdoc/OpenSSL/PKey/EC.html
- Java: https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/security/class-use/Signature.html (also consider BouncyCastle)
Tutorial: Webhook Signature Validation in Python
Benchling SDK
Our Python Benchling SDK has an implementation for verification of webhooks:
This was introduced in the 1.11.0 release of the SDK.
Tutorial: Webhook Signature Validation in TypeScript
Experimental feature: Custom webhook headers
This feature is in beta and may change without notice.
Benchling requires webhook URLs to be accessible over the public internet. If your endpoint is protected and requires authentication, you can include the necessary credentials as custom header values when configuring the webhook URL.

Benchling will include these headers in every webhook request sent to your URL.