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

B4X

Dim success As Boolean = 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.
Dim rawBody As ChilkatBinData
rawBody.Initialize
success = rawBody.LoadFile("qa_data/box_webhook_body.bin")
If success <> True Then
    Log(rawBody.LastErrorText)
    Return
End If

'  Read these fields case-insensitively from the incoming request headers.
'  For this offline example, enter the captured header values.
Dim timestamp As String = "BOX_DELIVERY_TIMESTAMP"
Dim primarySignature As String = "BOX_SIGNATURE_PRIMARY"
Dim secondarySignature As String = "BOX_SIGNATURE_SECONDARY"
Dim signatureVersion As String = "1"
Dim signatureAlgorithm As String = "HmacSHA256"
'  Retrieve configured keys from protected application configuration.
Dim primaryKey As String = "BOX_PRIMARY_SIGNATURE_KEY"
Dim secondaryKey As String = "BOX_SECONDARY_SIGNATURE_KEY"
If (signatureVersion <> "1") Or (signatureAlgorithm <> "HmacSHA256") Then
    Log("Unsupported signature version or algorithm.")
    Return
End If

Dim delivered As ChilkatDateTime
delivered.Initialize
success = delivered.SetFromTimestamp(timestamp)
If success <> True Then
    Log(delivered.LastErrorText)
    Return
End If

Dim now As ChilkatDateTime
now.Initialize
success = now.SetFromCurrentSystemTime
If success <> True Then
    Log(now.LastErrorText)
    Return
End If

Dim age As Int = 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) Then
    Log("Delivery timestamp is outside the accepted window.")
    Return
End If

Dim signedBytes As ChilkatBinData
signedBytes.Initialize
success = signedBytes.AppendBd(rawBody)
If success <> True Then
    Log(signedBytes.LastErrorText)
    Return
End If

success = signedBytes.AppendString(timestamp, "utf-8")
If success <> True Then
    Log(signedBytes.LastErrorText)
    Return
End If

Dim mac As ChilkatCrypt2
mac.Initialize("mac")
mac.MacAlgorithm = "hmac"
mac.HashAlgorithm = "sha256"
mac.EncodingMode = "base64"
success = mac.SetMacKeyString(primaryKey)
If success <> True Then
    Log(mac.LastErrorText)
    Return
End If

Dim expectedPrimary As String = mac.MacBdENC(signedBytes)
If mac.LastMethodSuccess <> True Then
    Log(mac.LastErrorText)
    Return
End If

success = mac.SetMacKeyString(secondaryKey)
If success <> True Then
    Log(mac.LastErrorText)
    Return
End If

Dim expectedSecondary As String = mac.MacBdENC(signedBytes)
If mac.LastMethodSuccess <> True Then
    Log(mac.LastErrorText)
    Return
End If

'  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.
Dim random As ChilkatPrng
random.Initialize
Dim comparisonKey As String = random.GenRandom(32, "base64")
If random.LastMethodSuccess <> True Then
    Log(random.LastErrorText)
    Return
End If

success = mac.SetMacKeyEncoded(comparisonKey, "base64")
If success <> True Then
    Log(mac.LastErrorText)
    Return
End If

Dim pExpected As String = mac.MacStringENC(expectedPrimary)
If mac.LastMethodSuccess <> True Then
    Log(mac.LastErrorText)
    Return
End If

Dim pReceived As String = mac.MacStringENC(primarySignature)
If mac.LastMethodSuccess <> True Then
    Log(mac.LastErrorText)
    Return
End If

Dim sExpected As String = mac.MacStringENC(expectedSecondary)
If mac.LastMethodSuccess <> True Then
    Log(mac.LastErrorText)
    Return
End If

Dim sReceived As String = mac.MacStringENC(secondarySignature)
If mac.LastMethodSuccess <> True Then
    Log(mac.LastErrorText)
    Return
End If

Dim validPrimary As Boolean = (primaryKey <> "") And (primarySignature <> "") And (pExpected = pReceived)
Dim validSecondary As Boolean = (secondaryKey <> "") And (secondarySignature <> "") And (sExpected = sReceived)
If (validPrimary = False) And (validSecondary = False) Then
    Log("Signature verification failed.")
    Return
End If

'  Parse JSON only after signature verification.
Dim webhookEvent As ChilkatJsonObject
webhookEvent.Initialize
success = webhookEvent.Load(rawBody.GetString("utf-8"))
If success <> True Then
    Log(webhookEvent.LastErrorText)
    Return
End If

Log("Verified event ID: " & webhookEvent.StringOf("id"))
Log("Trigger: " & webhookEvent.StringOf("trigger"))
'  Deduplicate using event.id, not BOX-DELIVERY-ID, which changes on retries.
'  Verify the target belongs to your configured webhook before dispatching work.