Company/Classroom/Enterprise Settings - Webhooks
Only available for
Administrators can use webhooks to check data access integrity, ensuring that a notification was really sent by Onshape, and that it has not been tampered with in transit. Enabling webhook basic authentication populates the Authorization header in all webhook requests.
To navigate to your Webhooks settings in Onshape, click on your Account user icon (
) in the top right corner of your Onshape window. This opens a dropdown menu. Click Company/Classroom/Enterprise settings.
Click Webhooks in the list on the left side of the page:
Company settings > Webhooks
Enterprise settings > Webhooks
Webhooks settings
Administrators can use webhooks to check data access integrity, ensuring that a notification was really sent by Onshape, and that it has not been tampered with in transit. Enabling webhook basic authentication populates the Authorization header in all webhook requests. Webhook signatures configures webhooks to use signatures to protect against attacks. Generate primary and secondary keys to rotate keys in your production application. This allows Administrators to deprecate or swap keys without breaking the current connection. If either key matches, it will be accepted as valid by Onshape. Copy to clipboard sends the related key to your clipboard. Reset removes the key from the related field. Once primary keys are generated, click Save changes to accept the entries.
Administrators should ensure that all webhooks are to secured end point locations (https), as this data is not encrypted.
The signature values can be matched by the webhook target using the following structure:
Signature = <Base64<HMAC256-digest<<timestamp header value>.<webhook payload>>>
Onshape webhooks contain the following additional headers:
-
X-onshape-webhook-timestamp - Time stamp signifying when the webhook was sent
-
X-onshape-webhook-signature-primary - Present if the primary signature key is specified in the company settings
-
X-onshape-webhook-signature-secondary - Present if the secondary signature key is specified in the company settings
Code samples
JAVA
void matchSignatureHeader(String messageBody, String timestamp, String signatureKey, String signature) throws Exception {
String payload = timestamp + "." + messageBody;
String algorithm = "HmacSHA256";
Mac mac = Mac.getInstance(algorithm);
mac.init(new SecretKeySpec(signatureKey.getBytes(), algorithm));
byte[] payloadBytes = mac.doFinal(payload.getBytes());
Assert.assertArrayEquals(payloadBytes, Base64.decodeBase64(signature.getBytes()));
}
NODE.JS
const crypto = require('crypto');
……
var signatureKey; // The primary or secondary key
var message = timestampHeader + "." + rawPayload; // The timestamp header and the webhook payload
var hashValue = crypto.createHmac('SHA256', signatureKey).update(message).digest('base64');
if (hashValue === signatureHeader) { // signatureHeader is the primary or secondary signature header received with the webhook
// Signatures match
}