C# 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.

C#

bool 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.
Chilkat.BinData rawBody = new Chilkat.BinData();
success = rawBody.LoadFile("qa_data/box_webhook_body.bin");
if (success != true) {
    Debug.WriteLine(rawBody.LastErrorText);
    return;
}

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

Chilkat.CkDateTime delivered = new Chilkat.CkDateTime();
success = delivered.SetFromTimestamp(timestamp);
if (success != true) {
    Debug.WriteLine(delivered.LastErrorText);
    return;
}

Chilkat.CkDateTime now = new Chilkat.CkDateTime();
success = now.SetFromCurrentSystemTime();
if (success != true) {
    Debug.WriteLine(now.LastErrorText);
    return;
}

int age = Convert.ToInt32(now.GetAsUnixTime(false)) - Convert.ToInt32(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)) {
    Debug.WriteLine("Delivery timestamp is outside the accepted window.");
    return;
}

Chilkat.BinData signedBytes = new Chilkat.BinData();
success = signedBytes.AppendBd(rawBody);
if (success != true) {
    Debug.WriteLine(signedBytes.LastErrorText);
    return;
}

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

Chilkat.Crypt2 mac = new Chilkat.Crypt2();
mac.MacAlgorithm = "hmac";
mac.HashAlgorithm = "sha256";
mac.EncodingMode = "base64";
success = mac.SetMacKeyString(primaryKey);
if (success != true) {
    Debug.WriteLine(mac.LastErrorText);
    return;
}

string expectedPrimary = mac.MacBdENC(signedBytes);
if (mac.LastMethodSuccess != true) {
    Debug.WriteLine(mac.LastErrorText);
    return;
}

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

string expectedSecondary = mac.MacBdENC(signedBytes);
if (mac.LastMethodSuccess != true) {
    Debug.WriteLine(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.
Chilkat.Prng random = new Chilkat.Prng();
string comparisonKey = random.GenRandom(32,"base64");
if (random.LastMethodSuccess != true) {
    Debug.WriteLine(random.LastErrorText);
    return;
}

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

string pExpected = mac.MacStringENC(expectedPrimary);
if (mac.LastMethodSuccess != true) {
    Debug.WriteLine(mac.LastErrorText);
    return;
}

string pReceived = mac.MacStringENC(primarySignature);
if (mac.LastMethodSuccess != true) {
    Debug.WriteLine(mac.LastErrorText);
    return;
}

string sExpected = mac.MacStringENC(expectedSecondary);
if (mac.LastMethodSuccess != true) {
    Debug.WriteLine(mac.LastErrorText);
    return;
}

string sReceived = mac.MacStringENC(secondarySignature);
if (mac.LastMethodSuccess != true) {
    Debug.WriteLine(mac.LastErrorText);
    return;
}

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

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

Debug.WriteLine("Verified event ID: " + webhookEvent.StringOf("id"));
Debug.WriteLine("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.