Webhook security

Receiving Benchling In Vivo webhooks requires hosting a publicly accessible HTTPS endpoint that accepts application/json POST requests. Your endpoint should be protected using one of the authentication mechanisms supported by Benchling In Vivo, such as custom authentication headers.

In addition to endpoint authentication, Benchling In Vivo includes a cryptographic signature with every webhook request. Verifying this signature provides an additional layer of security, allowing you to confirm that the request originated from Benchling In Vivo and that the payload has not been tampered with.

Signature Verification

Every webhook request includes a Signature HTTP header containing an HMAC-SHA256 signature of the request body.

Signature Details:

The signature is computed over the entire JSON request body, which includes all fields:

{
  "id": "whe_7E5H2v4X0hfhqLVmZg9HYZ",
  "client_id": "your-client-uuid",
  "event": "animal.created",
  "version": "2022-12-14",
  "created_at": "2024-01-15T10:30:00.000000Z",
  "payload": {
    "//": "event-specific data"
  }
}

Verifying Webhooks Manually

To verify a webhook request is authentic:

1. Extract the Signature header from the incoming HTTP request
2. Get the raw request body as bytes (before any JSON parsing)
3. Compute HMAC-SHA256 using your signing_secret as the key
4. Convert the result to a lowercase hexadecimal string
5. Compare with the Signature header value using a constant-time comparison

Most programming languages provide libraries for computing HMAC-SHA256 signatures. The following Node.js example demonstrates the verification process. This is provided as a reference only and may become outdated—consult your language’s documentation for current best practices.

Node.js Example:

const crypto = require('crypto');
function verifyWebhook(requestBody, signatureHeader, signingSecret) {
    if (typeof signatureHeader !== 'string') return false;
    const expected = crypto
        .createHmac('sha256', signingSecret)
        .update(requestBody)
        .digest();
    const provided = Buffer.from(signatureHeader, 'hex');
    // timingSafeEqual throws on buffers of different lengths, so check first.
    // Use constant-time comparison to prevent timing attacks.
    return expected.length === provided.length &&
        crypto.timingSafeEqual(expected, provided);
}