PHP Extension 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.

PHP Extension

<?php

include("chilkat.php");

$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 = new CkBinData();
$success = $rawBody->LoadFile('qa_data/box_webhook_body.bin');
if ($success != true) {
    print $rawBody->lastErrorText() . "\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.' . "\n";
    exit;
}

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

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

$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) or ($age < -60)) {
    print 'Delivery timestamp is outside the accepted window.' . "\n";
    exit;
}

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

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

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

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

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

$expectedSecondary = $mac->macBdENC($signedBytes);
if ($mac->get_LastMethodSuccess() != true) {
    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.
$random = new CkPrng();
$comparisonKey = $random->genRandom(32,'base64');
if ($random->get_LastMethodSuccess() != true) {
    print $random->lastErrorText() . "\n";
    exit;
}

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

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

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

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

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

$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;
}

//  Parse JSON only after signature verification.
$webhookEvent = new CkJsonObject();
$success = $webhookEvent->Load($rawBody->getString('utf-8'));
if ($success != true) {
    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.

?>