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

Perl

use chilkat();

$success = 0;

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

$success = 0;

#  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 != 1) {
    print $rawBody->lastErrorText() . "\r\n";
    exit;
}

#  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." . "\r\n";
    exit;
}

$delivered = chilkat::CkDateTime->new();
$success = $delivered->SetFromTimestamp($timestamp);
if ($success != 1) {
    print $delivered->lastErrorText() . "\r\n";
    exit;
}

$now = chilkat::CkDateTime->new();
$success = $now->SetFromCurrentSystemTime();
if ($success != 1) {
    print $now->lastErrorText() . "\r\n";
    exit;
}

$age = $now->GetAsUnixTime(0) - $delivered->GetAsUnixTime(0);
#  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." . "\r\n";
    exit;
}

$signedBytes = chilkat::CkBinData->new();
$success = $signedBytes->AppendBd($rawBody);
if ($success != 1) {
    print $signedBytes->lastErrorText() . "\r\n";
    exit;
}

$success = $signedBytes->AppendString($timestamp,"utf-8");
if ($success != 1) {
    print $signedBytes->lastErrorText() . "\r\n";
    exit;
}

$mac = chilkat::CkCrypt2->new();
$mac->put_MacAlgorithm("hmac");
$mac->put_HashAlgorithm("sha256");
$mac->put_EncodingMode("base64");
$success = $mac->SetMacKeyString($primaryKey);
if ($success != 1) {
    print $mac->lastErrorText() . "\r\n";
    exit;
}

$expectedPrimary = $mac->macBdENC($signedBytes);
if ($mac->get_LastMethodSuccess() != 1) {
    print $mac->lastErrorText() . "\r\n";
    exit;
}

$success = $mac->SetMacKeyString($secondaryKey);
if ($success != 1) {
    print $mac->lastErrorText() . "\r\n";
    exit;
}

$expectedSecondary = $mac->macBdENC($signedBytes);
if ($mac->get_LastMethodSuccess() != 1) {
    print $mac->lastErrorText() . "\r\n";
    exit;
}

#  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() != 1) {
    print $random->lastErrorText() . "\r\n";
    exit;
}

$success = $mac->SetMacKeyEncoded($comparisonKey,"base64");
if ($success != 1) {
    print $mac->lastErrorText() . "\r\n";
    exit;
}

$pExpected = $mac->macStringENC($expectedPrimary);
if ($mac->get_LastMethodSuccess() != 1) {
    print $mac->lastErrorText() . "\r\n";
    exit;
}

$pReceived = $mac->macStringENC($primarySignature);
if ($mac->get_LastMethodSuccess() != 1) {
    print $mac->lastErrorText() . "\r\n";
    exit;
}

$sExpected = $mac->macStringENC($expectedSecondary);
if ($mac->get_LastMethodSuccess() != 1) {
    print $mac->lastErrorText() . "\r\n";
    exit;
}

$sReceived = $mac->macStringENC($secondarySignature);
if ($mac->get_LastMethodSuccess() != 1) {
    print $mac->lastErrorText() . "\r\n";
    exit;
}

$validPrimary = ($primaryKey != "") and ($primarySignature != "") and ($pExpected == $pReceived);
$validSecondary = ($secondaryKey != "") and ($secondarySignature != "") and ($sExpected == $sReceived);
if (($validPrimary == 0) and ($validSecondary == 0)) {
    print "Signature verification failed." . "\r\n";
    exit;
}

#  Parse JSON only after signature verification.
$webhookEvent = chilkat::CkJsonObject->new();
$success = $webhookEvent->Load($rawBody->getString("utf-8"));
if ($success != 1) {
    print $webhookEvent->lastErrorText() . "\r\n";
    exit;
}

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