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.

Chilkat2 Perl

use strict;
use warnings;
use Chilkat2;

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

my $success = 0;

# Save the exact HTTP body bytes to this file, without JSON reserialization.
my $rawBody = Chilkat2::BinData->new;
$success = $rawBody->LoadFile('qa_data/box_webhook_body.bin');
if (!$success) {
    print $rawBody->LastErrorText, "\n";
    exit;
}

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

my $delivered = Chilkat2::DateTime->new;
$success = $delivered->SetFromTimestamp($timestamp);
if (!$success) {
    print $delivered->LastErrorText, "\n";
    exit;
}

my $now = Chilkat2::DateTime->new;
$success = $now->SetFromCurrentSystemTime();
if (!$success) {
    print $now->LastErrorText, "\n";
    exit;
}

my $age = int($now->GetAsUnixTime(0)) - int($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) || ($age < -60)) {
    print "Delivery timestamp is outside the accepted window.\n";
    exit;
}

my $signedBytes = Chilkat2::BinData->new;
$success = $signedBytes->AppendBd($rawBody);
if (!$success) {
    print $signedBytes->LastErrorText, "\n";
    exit;
}

$success = $signedBytes->AppendString($timestamp, 'utf-8');
if (!$success) {
    print $signedBytes->LastErrorText, "\n";
    exit;
}

my $mac = Chilkat2::Crypt2->new;
$mac->MacAlgorithm('hmac');
$mac->HashAlgorithm('sha256');
$mac->EncodingMode('base64');
$success = $mac->SetMacKeyString($primaryKey);
if (!$success) {
    print $mac->LastErrorText, "\n";
    exit;
}

my $expectedPrimary = $mac->MacBdENC($signedBytes);
if (!$mac->LastMethodSuccess) {
    print $mac->LastErrorText, "\n";
    exit;
}

$success = $mac->SetMacKeyString($secondaryKey);
if (!$success) {
    print $mac->LastErrorText, "\n";
    exit;
}

my $expectedSecondary = $mac->MacBdENC($signedBytes);
if (!$mac->LastMethodSuccess) {
    print $mac->LastErrorText, "\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.
my $random = Chilkat2::Prng->new;
my $comparisonKey = $random->GenRandom(32, 'base64');
if (!$random->LastMethodSuccess) {
    print $random->LastErrorText, "\n";
    exit;
}

$success = $mac->SetMacKeyEncoded($comparisonKey, 'base64');
if (!$success) {
    print $mac->LastErrorText, "\n";
    exit;
}

my $pExpected = $mac->MacStringENC($expectedPrimary);
if (!$mac->LastMethodSuccess) {
    print $mac->LastErrorText, "\n";
    exit;
}

my $pReceived = $mac->MacStringENC($primarySignature);
if (!$mac->LastMethodSuccess) {
    print $mac->LastErrorText, "\n";
    exit;
}

my $sExpected = $mac->MacStringENC($expectedSecondary);
if (!$mac->LastMethodSuccess) {
    print $mac->LastErrorText, "\n";
    exit;
}

my $sReceived = $mac->MacStringENC($secondarySignature);
if (!$mac->LastMethodSuccess) {
    print $mac->LastErrorText, "\n";
    exit;
}

my $validPrimary = ($primaryKey ne '') && (($primarySignature ne '') && ($pExpected eq $pReceived));
my $validSecondary = ($secondaryKey ne '') && (($secondarySignature ne '') && ($sExpected eq $sReceived));
if ((!$validPrimary) && (!$validSecondary)) {
    print "Signature verification failed.\n";
    exit;
}

# Parse JSON only after signature verification.
my $webhookEvent = Chilkat2::JsonObject->new;
$success = $webhookEvent->Load($rawBody->GetString('utf-8'));
if (!$success) {
    print $webhookEvent->LastErrorText, "\n";
    exit;
}

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.