Node.js Requires Chilkat v11.5.0+

Box: Verify a Captured V2 Webhook Signature

See more Box Examples

Verify raw payload bytes and captured headers using the configured primary and secondary signing keys. The example rejects stale/future timestamps and compares randomized HMACs of the signatures to avoid exposing a signature-prefix timing comparison. It does not host an HTTP listener. The receiver must persist/deduplicate the verified event and acknowledge promptly.

See the Box API guide for setup and the complete workflow.

Node.js

NODEJS_PRELUDE

function chilkatExample() {

    var success = false;

    //  Requires Chilkat 11.5.0 or later and a previously unlocked Chilkat bundle.
    //  See Global Unlock Sample.
    //  Guide: Box API Guide.

    success = false;

    //  Save the exact HTTP body bytes to this file, without JSON reserialization.
    var rawBody = new chilkat.BinData();
    success = rawBody.LoadFile("qa_data/box_webhook_body.bin");
    if (success !== true) {
        console.log(rawBody.LastErrorText);
        return;
    }

    //  Read these fields case-insensitively from the incoming request headers.
    //  For this offline example, enter the captured header values.
    var timestamp = "BOX_DELIVERY_TIMESTAMP";
    var primarySignature = "BOX_SIGNATURE_PRIMARY";
    var secondarySignature = "BOX_SIGNATURE_SECONDARY";
    var signatureVersion = "1";
    var signatureAlgorithm = "HmacSHA256";
    //  Retrieve configured keys from protected application configuration.
    var primaryKey = "BOX_PRIMARY_SIGNATURE_KEY";
    var secondaryKey = "BOX_SECONDARY_SIGNATURE_KEY";
    if ((signatureVersion !== "1") || (signatureAlgorithm !== "HmacSHA256")) {
        console.log("Unsupported signature version or algorithm.");
        return;
    }

    var delivered = new chilkat.CkDateTime();
    success = delivered.SetFromTimestamp(timestamp);
    if (success !== true) {
        console.log(delivered.LastErrorText);
        return;
    }

    var now = new chilkat.CkDateTime();
    success = now.SetFromCurrentSystemTime();
    if (success !== true) {
        console.log(now.LastErrorText);
        return;
    }

    var age = now.GetAsUnixTime(false) - delivered.GetAsUnixTime(false);
    //  Box recommends rejecting deliveries older than ten minutes.
    //  Allow at most 60 seconds of future clock skew; keep the server clock synchronized.
    if ((age > 600) || (age < -60)) {
        console.log("Delivery timestamp is outside the accepted window.");
        return;
    }

    var signedBytes = new chilkat.BinData();
    success = signedBytes.AppendBd(rawBody);
    if (success !== true) {
        console.log(signedBytes.LastErrorText);
        return;
    }

    success = signedBytes.AppendString(timestamp,"utf-8");
    if (success !== true) {
        console.log(signedBytes.LastErrorText);
        return;
    }

    var mac = new chilkat.Crypt2();
    mac.MacAlgorithm = "hmac";
    mac.HashAlgorithm = "sha256";
    mac.EncodingMode = "base64";
    success = mac.SetMacKeyString(primaryKey);
    if (success !== true) {
        console.log(mac.LastErrorText);
        return;
    }

    var expectedPrimary = mac.MacBdENC(signedBytes);
    if (mac.LastMethodSuccess !== true) {
        console.log(mac.LastErrorText);
        return;
    }

    success = mac.SetMacKeyString(secondaryKey);
    if (success !== true) {
        console.log(mac.LastErrorText);
        return;
    }

    var expectedSecondary = mac.MacBdENC(signedBytes);
    if (mac.LastMethodSuccess !== true) {
        console.log(mac.LastErrorText);
        return;
    }

    //  Blind both sides with a fresh secret random key before equality comparison.
    //  Never compare the original HMAC strings using a prefix-short-circuit comparison.
    //  A host-language receiver can instead use its standard constant-time byte comparison.
    var random = new chilkat.Prng();
    var comparisonKey = random.GenRandom(32,"base64");
    if (random.LastMethodSuccess !== true) {
        console.log(random.LastErrorText);
        return;
    }

    success = mac.SetMacKeyEncoded(comparisonKey,"base64");
    if (success !== true) {
        console.log(mac.LastErrorText);
        return;
    }

    var pExpected = mac.MacStringENC(expectedPrimary);
    if (mac.LastMethodSuccess !== true) {
        console.log(mac.LastErrorText);
        return;
    }

    var pReceived = mac.MacStringENC(primarySignature);
    if (mac.LastMethodSuccess !== true) {
        console.log(mac.LastErrorText);
        return;
    }

    var sExpected = mac.MacStringENC(expectedSecondary);
    if (mac.LastMethodSuccess !== true) {
        console.log(mac.LastErrorText);
        return;
    }

    var sReceived = mac.MacStringENC(secondarySignature);
    if (mac.LastMethodSuccess !== true) {
        console.log(mac.LastErrorText);
        return;
    }

    var validPrimary = (primaryKey !== "") && (primarySignature !== "") && (pExpected == pReceived);
    var validSecondary = (secondaryKey !== "") && (secondarySignature !== "") && (sExpected == sReceived);
    if ((validPrimary == false) && (validSecondary == false)) {
        console.log("Signature verification failed.");
        return;
    }

    //  Parse JSON only after signature verification.
    var webhookEvent = new chilkat.JsonObject();
    success = webhookEvent.Load(rawBody.GetString("utf-8"));
    if (success !== true) {
        console.log(webhookEvent.LastErrorText);
        return;
    }

    console.log("Verified event ID: " + webhookEvent.StringOf("id"));
    console.log("Trigger: " + webhookEvent.StringOf("trigger"));
    //  Deduplicate using event.id, not BOX-DELIVERY-ID, which changes on retries.
    //  Verify the target belongs to your configured webhook before dispatching work.

}

chilkatExample();