Delphi DLL 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.

Delphi DLL

var
success: Boolean;
rawBody: HCkBinData;
timestamp: PWideChar;
primarySignature: PWideChar;
secondarySignature: PWideChar;
signatureVersion: PWideChar;
signatureAlgorithm: PWideChar;
primaryKey: PWideChar;
secondaryKey: PWideChar;
delivered: HCkDateTime;
now: HCkDateTime;
age: Integer;
signedBytes: HCkBinData;
mac: HCkCrypt2;
expectedPrimary: PWideChar;
expectedSecondary: PWideChar;
random: HCkPrng;
comparisonKey: PWideChar;
pExpected: PWideChar;
pReceived: PWideChar;
sExpected: PWideChar;
sReceived: PWideChar;
validPrimary: Boolean;
validSecondary: Boolean;
webhookEvent: HCkJsonObject;

begin
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 := CkBinData_Create();
success := CkBinData_LoadFile(rawBody,'qa_data/box_webhook_body.bin');
if (success <> True) then
  begin
    Memo1.Lines.Add(CkBinData__lastErrorText(rawBody));
    Exit;
  end;
//  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')) then
  begin
    Memo1.Lines.Add('Unsupported signature version or algorithm.');
    Exit;
  end;
delivered := CkDateTime_Create();
success := CkDateTime_SetFromTimestamp(delivered,timestamp);
if (success <> True) then
  begin
    Memo1.Lines.Add(CkDateTime__lastErrorText(delivered));
    Exit;
  end;
now := CkDateTime_Create();
success := CkDateTime_SetFromCurrentSystemTime(now);
if (success <> True) then
  begin
    Memo1.Lines.Add(CkDateTime__lastErrorText(now));
    Exit;
  end;
age := StrToInt(CkDateTime_GetAsUnixTime(now,False)) - StrToInt(CkDateTime_GetAsUnixTime(delivered,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)) then
  begin
    Memo1.Lines.Add('Delivery timestamp is outside the accepted window.');
    Exit;
  end;
signedBytes := CkBinData_Create();
success := CkBinData_AppendBd(signedBytes,rawBody);
if (success <> True) then
  begin
    Memo1.Lines.Add(CkBinData__lastErrorText(signedBytes));
    Exit;
  end;
success := CkBinData_AppendString(signedBytes,timestamp,'utf-8');
if (success <> True) then
  begin
    Memo1.Lines.Add(CkBinData__lastErrorText(signedBytes));
    Exit;
  end;
mac := CkCrypt2_Create();
CkCrypt2_putMacAlgorithm(mac,'hmac');
CkCrypt2_putHashAlgorithm(mac,'sha256');
CkCrypt2_putEncodingMode(mac,'base64');
success := CkCrypt2_SetMacKeyString(mac,primaryKey);
if (success <> True) then
  begin
    Memo1.Lines.Add(CkCrypt2__lastErrorText(mac));
    Exit;
  end;
expectedPrimary := CkCrypt2__macBdENC(mac,signedBytes);
if (CkCrypt2_getLastMethodSuccess(mac) <> True) then
  begin
    Memo1.Lines.Add(CkCrypt2__lastErrorText(mac));
    Exit;
  end;
success := CkCrypt2_SetMacKeyString(mac,secondaryKey);
if (success <> True) then
  begin
    Memo1.Lines.Add(CkCrypt2__lastErrorText(mac));
    Exit;
  end;
expectedSecondary := CkCrypt2__macBdENC(mac,signedBytes);
if (CkCrypt2_getLastMethodSuccess(mac) <> True) then
  begin
    Memo1.Lines.Add(CkCrypt2__lastErrorText(mac));
    Exit;
  end;
//  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 := CkPrng_Create();
comparisonKey := CkPrng__genRandom(random,32,'base64');
if (CkPrng_getLastMethodSuccess(random) <> True) then
  begin
    Memo1.Lines.Add(CkPrng__lastErrorText(random));
    Exit;
  end;
success := CkCrypt2_SetMacKeyEncoded(mac,comparisonKey,'base64');
if (success <> True) then
  begin
    Memo1.Lines.Add(CkCrypt2__lastErrorText(mac));
    Exit;
  end;
pExpected := CkCrypt2__macStringENC(mac,expectedPrimary);
if (CkCrypt2_getLastMethodSuccess(mac) <> True) then
  begin
    Memo1.Lines.Add(CkCrypt2__lastErrorText(mac));
    Exit;
  end;
pReceived := CkCrypt2__macStringENC(mac,primarySignature);
if (CkCrypt2_getLastMethodSuccess(mac) <> True) then
  begin
    Memo1.Lines.Add(CkCrypt2__lastErrorText(mac));
    Exit;
  end;
sExpected := CkCrypt2__macStringENC(mac,expectedSecondary);
if (CkCrypt2_getLastMethodSuccess(mac) <> True) then
  begin
    Memo1.Lines.Add(CkCrypt2__lastErrorText(mac));
    Exit;
  end;
sReceived := CkCrypt2__macStringENC(mac,secondarySignature);
if (CkCrypt2_getLastMethodSuccess(mac) <> True) then
  begin
    Memo1.Lines.Add(CkCrypt2__lastErrorText(mac));
    Exit;
  end;
validPrimary := (primaryKey <> '') and (primarySignature <> '') and (pExpected = pReceived);
validSecondary := (secondaryKey <> '') and (secondarySignature <> '') and (sExpected = sReceived);
if ((validPrimary = False) and (validSecondary = False)) then
  begin
    Memo1.Lines.Add('Signature verification failed.');
    Exit;
  end;
//  Parse JSON only after signature verification.
webhookEvent := CkJsonObject_Create();
success := CkJsonObject_Load(webhookEvent,CkBinData__getString(rawBody,'utf-8'));
if (success <> True) then
  begin
    Memo1.Lines.Add(CkJsonObject__lastErrorText(webhookEvent));
    Exit;
  end;
Memo1.Lines.Add('Verified event ID: ' + CkJsonObject__stringOf(webhookEvent,'id'));
Memo1.Lines.Add('Trigger: ' + CkJsonObject__stringOf(webhookEvent,'trigger'));
//  Deduplicate using event.id, not BOX-DELIVERY-ID, which changes on retries.
//  Verify the target belongs to your configured webhook before dispatching work.

CkBinData_Dispose(rawBody);
CkDateTime_Dispose(delivered);
CkDateTime_Dispose(now);
CkBinData_Dispose(signedBytes);
CkCrypt2_Dispose(mac);
CkPrng_Dispose(random);
CkJsonObject_Dispose(webhookEvent);