Ruby 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.

Ruby

require 'chilkat'

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.
rawBody = Chilkat::CkBinData.new()
success = rawBody.LoadFile("qa_data/box_webhook_body.bin")
if (success != true)
    print rawBody.lastErrorText() + "\n";
    exit
end

#  Read these fields case-insensitively from the incoming request headers.
#  For this offline example, enter the captured header values.
timestamp = "BOX_DELIVERY_TIMESTAMP"
primarySignature = "BOX_SIGNATURE_PRIMARY"
secondarySignature = "BOX_SIGNATURE_SECONDARY"
signatureVersion = "1"
signatureAlgorithm = "HmacSHA256"
#  Retrieve configured keys from protected application configuration.
primaryKey = "BOX_PRIMARY_SIGNATURE_KEY"
secondaryKey = "BOX_SECONDARY_SIGNATURE_KEY"
if ((signatureVersion != "1") or (signatureAlgorithm != "HmacSHA256"))
    print "Unsupported signature version or algorithm." + "\n";
    exit
end

delivered = Chilkat::CkDateTime.new()
success = delivered.SetFromTimestamp(timestamp)
if (success != true)
    print delivered.lastErrorText() + "\n";
    exit
end

now = Chilkat::CkDateTime.new()
success = now.SetFromCurrentSystemTime()
if (success != true)
    print now.lastErrorText() + "\n";
    exit
end

age = now.GetAsUnixTime(false).to_i() - delivered.GetAsUnixTime(false).to_i()
#  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) or (age < -60))
    print "Delivery timestamp is outside the accepted window." + "\n";
    exit
end

signedBytes = Chilkat::CkBinData.new()
success = signedBytes.AppendBd(rawBody)
if (success != true)
    print signedBytes.lastErrorText() + "\n";
    exit
end

success = signedBytes.AppendString(timestamp,"utf-8")
if (success != true)
    print signedBytes.lastErrorText() + "\n";
    exit
end

mac = Chilkat::CkCrypt2.new()
mac.put_MacAlgorithm("hmac")
mac.put_HashAlgorithm("sha256")
mac.put_EncodingMode("base64")
success = mac.SetMacKeyString(primaryKey)
if (success != true)
    print mac.lastErrorText() + "\n";
    exit
end

expectedPrimary = mac.macBdENC(signedBytes)
if (mac.get_LastMethodSuccess() != true)
    print mac.lastErrorText() + "\n";
    exit
end

success = mac.SetMacKeyString(secondaryKey)
if (success != true)
    print mac.lastErrorText() + "\n";
    exit
end

expectedSecondary = mac.macBdENC(signedBytes)
if (mac.get_LastMethodSuccess() != true)
    print mac.lastErrorText() + "\n";
    exit
end

#  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.
random = Chilkat::CkPrng.new()
comparisonKey = random.genRandom(32,"base64")
if (random.get_LastMethodSuccess() != true)
    print random.lastErrorText() + "\n";
    exit
end

success = mac.SetMacKeyEncoded(comparisonKey,"base64")
if (success != true)
    print mac.lastErrorText() + "\n";
    exit
end

pExpected = mac.macStringENC(expectedPrimary)
if (mac.get_LastMethodSuccess() != true)
    print mac.lastErrorText() + "\n";
    exit
end

pReceived = mac.macStringENC(primarySignature)
if (mac.get_LastMethodSuccess() != true)
    print mac.lastErrorText() + "\n";
    exit
end

sExpected = mac.macStringENC(expectedSecondary)
if (mac.get_LastMethodSuccess() != true)
    print mac.lastErrorText() + "\n";
    exit
end

sReceived = mac.macStringENC(secondarySignature)
if (mac.get_LastMethodSuccess() != true)
    print mac.lastErrorText() + "\n";
    exit
end

validPrimary = (primaryKey != "") and (primarySignature != "") and (pExpected == pReceived)
validSecondary = (secondaryKey != "") and (secondarySignature != "") and (sExpected == sReceived)
if ((validPrimary == false) and (validSecondary == false))
    print "Signature verification failed." + "\n";
    exit
end

#  Parse JSON only after signature verification.
webhookEvent = Chilkat::CkJsonObject.new()
success = webhookEvent.Load(rawBody.getString("utf-8"))
if (success != true)
    print webhookEvent.lastErrorText() + "\n";
    exit
end

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