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

<?php

use Chilkat2\BinData;
use Chilkat2\Crypt2;
use Chilkat2\DateTime;
use Chilkat2\JsonObject;
use Chilkat2\Prng;

$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 BinData();
try {
    $rawBody->LoadFile('qa_data/box_webhook_body.bin');
} catch (\Chilkat2\Exception $e) {
    echo $e->getMessage(), "\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') || ($signatureAlgorithm !== 'HmacSHA256')) {
    echo "Unsupported signature version or algorithm.\n";
    exit;
}

$delivered = new DateTime();
try {
    $delivered->SetFromTimestamp($timestamp);

    $now = new DateTime();
    $now->SetFromCurrentSystemTime();
} catch (\Chilkat2\Exception $e) {
    echo $e->getMessage(), "\n";
    exit;
}

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

$signedBytes = new BinData();
try {
    $signedBytes->AppendBd($rawBody);

    $signedBytes->AppendString($timestamp, 'utf-8');

    $mac = new Crypt2();
    $mac->MacAlgorithm = 'hmac';
    $mac->HashAlgorithm = 'sha256';
    $mac->EncodingMode = 'base64';
    $mac->SetMacKeyString($primaryKey);

    $expectedPrimary = $mac->MacBdENC($signedBytes);

    $mac->SetMacKeyString($secondaryKey);

    $expectedSecondary = $mac->MacBdENC($signedBytes);

    // 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 Prng();
    $comparisonKey = $random->GenRandom(32, 'base64');

    $mac->SetMacKeyEncoded($comparisonKey, 'base64');

    $pExpected = $mac->MacStringENC($expectedPrimary);

    $pReceived = $mac->MacStringENC($primarySignature);

    $sExpected = $mac->MacStringENC($expectedSecondary);

    $sReceived = $mac->MacStringENC($secondarySignature);
} catch (\Chilkat2\Exception $e) {
    echo $e->getMessage(), "\n";
    exit;
}

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

// Parse JSON only after signature verification.
$webhookEvent = new JsonObject();
try {
    $webhookEvent->Load($rawBody->GetString('utf-8'));
} catch (\Chilkat2\Exception $e) {
    echo $e->getMessage(), "\n";
    exit;
}

echo 'Verified event ID: ', $webhookEvent->StringOf('id'), "\n";
echo '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.