How to Verify Payload Signature
Your callback URL is reachable by anyone on the internet, so your server cannot assume that a request arriving at it came from Autodesk. This walkthrough demonstrates how to verify that a callback genuinely came from the Webhooks service, using a simple Node.js server.
Verification is separate from authorization, and the two use different credentials:
- When your app calls the Webhooks service, it sends an OAuth access token in the
Authorizationheader. The access token authorizes calls to Webhooks operations, such as creating or deleting a webhook. See Authentication for Webhooks. - When the Webhooks service calls your callback URL, no access token is involved. Instead, the Webhooks service signs the payload with the secret token you set, and your server checks that signature.
How Verification Works
- You set a secret token, using the Create Secret Token operation, or per webhook using the Update a Webhook operation. You choose the value, and only you and the Webhooks service know it.
- When an event occurs, the Webhooks service computes an HMAC hash signature of the callback payload using your secret token as the key.
- The Webhooks service sends the callback to your callback URL with the signature in the
x-adsk-signatureheader. The value is prefixed withsha1hash=. - Your server recomputes the signature from the body it received, using the same secret token, and compares the result with the header value.
- If the two match, the callback came from the Webhooks service and the payload was not altered in transit. If they do not match, reject the request.
Compute the signature over the raw request body exactly as it was received. The example below uses the verify hook of body-parser for this reason, because it gives access to the raw body before it is parsed.
For background on the secret token, see Secret Token in API Basics.
Before You Begin
- Install Node.js.
- Set a secret token, as described in step 1 above. Keep the value out of your source code, for example in an environment variable.
- Have a callback URL that the Webhooks service can reach. See Configuring Your Server.
Verify Using Node.js
Create a New Server With Express.js
Open your command line and run $ npm init to initialize a new node project.
Create a file called app.js and add the following lines.
var express = require('express');
var app = express();
app.listen(3000, function () {
console.log('Listening on port 3000!');
});
Now run your server:
$ node app.js
Listening on port 3000!
Add a New Endpoint for the Callback
Create the path where you will receive webhook notifications.
app.post("/callback", function(req, res){
res.send();
});
Create a Webhook for Your Server
Now that your server is running, configure the Webhooks service to send notifications to it.
See the walkthrough for your service, for example Creating a Webhook (Data Management), and use your callback URL when you create the webhook.
{
"callbackUrl":"http://localhost:3000/callback",
"scope":{
"folder":"urn:adsk.wipprod:fs.folder:co.q2d7wQwVTJSICAdBl-REQw"
}
}
Note: the hook above uses localhost as the callback URL, and it will not be reachable from the Webhooks service. See Configuring Your Server for how to use ngrok to open a secure tunnel to localhost.
Configure the Server to Verify the Signature
This example uses the Crypto library bundled with Node to calculate the HMAC-SHA1 signature.
var bodyParser = require('body-parser');
var crypto = require('crypto');
var WEBHOOKS_SECRET = "<YOUR_TOKEN_HERE>";
function verifySignature(req, res, buf, encoding) {
const signature = req.header('x-adsk-signature');
if(!signature) { return; }
// use utf-8 encoding by default
const body = buf.toString(encoding);
const hmac = crypto.createHmac('sha1', WEBHOOKS_SECRET);
const calcSignature = 'sha1hash=' + hmac.update(body).digest('hex');
req.signature_match = (calcSignature === signature);
}
app.use(bodyParser.json({
inflate: true,
limit: '1024kb',
type: 'application/json',
verify: verifySignature
}));
app.post("/callback", function(req, res){
if(!req.signature_match) {
return res.status(403).send('not called from webhooks service');
}
res.status(204).send();
});
If the x-adsk-signature header is absent, the request was not signed. That happens when no secret token is set for the webhook, so confirm that you completed step 1 before treating an unsigned request as a failure.
Download the Full Example
var express = require('express');
var bodyParser = require('body-parser');
var crypto = require('crypto');
var app = express();
var WEBHOOKS_SECRET = "<YOUR_TOKEN_HERE>";
function verifySignature(req, res, buf, encoding) {
const signature = req.header('x-adsk-signature');
if(!signature) { return; }
// use utf-8 encoding by default
const body = buf.toString(encoding);
const hmac = crypto.createHmac('sha1', WEBHOOKS_SECRET);
const calcSignature = 'sha1hash=' + hmac.update(body).digest('hex');
req.signature_match = (calcSignature === signature);
}
app.use(bodyParser.json({
inflate: true,
limit: '1024kb',
type: 'application/json',
verify: verifySignature
}));
app.post("/callback", function(req, res){
if(!req.signature_match) {
return res.status(403).send('not called from webhooks service');
}
res.status(204).send();
// do whatever work needs to be done with the webhooks payload
const body = req.body;
console.log(body);
});
app.listen(3000, function () {
console.log('Listening on port 3000!');
});
Note that the callback responds before doing its work with the payload. Your callback must respond with a 2xx status code within 7 seconds, so acknowledge the callback first and process it afterwards.
Replacing a Secret Token
To replace an existing secret token with a new one, use the Update Secret Token operation.
There can be a delay of up to 10 minutes while the change takes effect. During that period, configure your callback to accept both the old and the new secret token value, so that all requests continue to be verified. Once the change has taken effect, stop accepting the old value.