Unicode C++ 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.

Unicode C++

#include <CkBinDataW.h>
#include <CkDateTimeW.h>
#include <CkCrypt2W.h>
#include <CkPrngW.h>
#include <CkJsonObjectW.h>

void ChilkatSample(void)
    {
    bool 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.
    CkBinDataW rawBody;
    success = rawBody.LoadFile(L"qa_data/box_webhook_body.bin");
    if (success != true) {
        wprintf(L"%s\n",rawBody.lastErrorText());
        return;
    }

    //  Read these fields case-insensitively from the incoming request headers.
    //  For this offline example, enter the captured header values.
    const wchar_t *timestamp = L"BOX_DELIVERY_TIMESTAMP";
    const wchar_t *primarySignature = L"BOX_SIGNATURE_PRIMARY";
    const wchar_t *secondarySignature = L"BOX_SIGNATURE_SECONDARY";
    const wchar_t *signatureVersion = L"1";
    const wchar_t *signatureAlgorithm = L"HmacSHA256";
    //  Retrieve configured keys from protected application configuration.
    const wchar_t *primaryKey = L"BOX_PRIMARY_SIGNATURE_KEY";
    const wchar_t *secondaryKey = L"BOX_SECONDARY_SIGNATURE_KEY";
    if ((signatureVersion != L"1") || (signatureAlgorithm != L"HmacSHA256")) {
        wprintf(L"Unsupported signature version or algorithm.\n");
        return;
    }

    CkDateTimeW delivered;
    success = delivered.SetFromTimestamp(timestamp);
    if (success != true) {
        wprintf(L"%s\n",delivered.lastErrorText());
        return;
    }

    CkDateTimeW now;
    success = now.SetFromCurrentSystemTime();
    if (success != true) {
        wprintf(L"%s\n",now.lastErrorText());
        return;
    }

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

    CkBinDataW signedBytes;
    success = signedBytes.AppendBd(rawBody);
    if (success != true) {
        wprintf(L"%s\n",signedBytes.lastErrorText());
        return;
    }

    success = signedBytes.AppendString(timestamp,L"utf-8");
    if (success != true) {
        wprintf(L"%s\n",signedBytes.lastErrorText());
        return;
    }

    CkCrypt2W mac;
    mac.put_MacAlgorithm(L"hmac");
    mac.put_HashAlgorithm(L"sha256");
    mac.put_EncodingMode(L"base64");
    success = mac.SetMacKeyString(primaryKey);
    if (success != true) {
        wprintf(L"%s\n",mac.lastErrorText());
        return;
    }

    const wchar_t *expectedPrimary = mac.macBdENC(signedBytes);
    if (mac.get_LastMethodSuccess() != true) {
        wprintf(L"%s\n",mac.lastErrorText());
        return;
    }

    success = mac.SetMacKeyString(secondaryKey);
    if (success != true) {
        wprintf(L"%s\n",mac.lastErrorText());
        return;
    }

    const wchar_t *expectedSecondary = mac.macBdENC(signedBytes);
    if (mac.get_LastMethodSuccess() != true) {
        wprintf(L"%s\n",mac.lastErrorText());
        return;
    }

    //  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.
    CkPrngW random;
    const wchar_t *comparisonKey = random.genRandom(32,L"base64");
    if (random.get_LastMethodSuccess() != true) {
        wprintf(L"%s\n",random.lastErrorText());
        return;
    }

    success = mac.SetMacKeyEncoded(comparisonKey,L"base64");
    if (success != true) {
        wprintf(L"%s\n",mac.lastErrorText());
        return;
    }

    const wchar_t *pExpected = mac.macStringENC(expectedPrimary);
    if (mac.get_LastMethodSuccess() != true) {
        wprintf(L"%s\n",mac.lastErrorText());
        return;
    }

    const wchar_t *pReceived = mac.macStringENC(primarySignature);
    if (mac.get_LastMethodSuccess() != true) {
        wprintf(L"%s\n",mac.lastErrorText());
        return;
    }

    const wchar_t *sExpected = mac.macStringENC(expectedSecondary);
    if (mac.get_LastMethodSuccess() != true) {
        wprintf(L"%s\n",mac.lastErrorText());
        return;
    }

    const wchar_t *sReceived = mac.macStringENC(secondarySignature);
    if (mac.get_LastMethodSuccess() != true) {
        wprintf(L"%s\n",mac.lastErrorText());
        return;
    }

    bool validPrimary = (primaryKey != L"") && (primarySignature != L"") && (pExpected == pReceived);
    bool validSecondary = (secondaryKey != L"") && (secondarySignature != L"") && (sExpected == sReceived);
    if ((validPrimary == false) && (validSecondary == false)) {
        wprintf(L"Signature verification failed.\n");
        return;
    }

    //  Parse JSON only after signature verification.
    CkJsonObjectW webhookEvent;
    success = webhookEvent.Load(rawBody.getString(L"utf-8"));
    if (success != true) {
        wprintf(L"%s\n",webhookEvent.lastErrorText());
        return;
    }

    wprintf(L"Verified event ID: %s\n",webhookEvent.stringOf(L"id"));
    wprintf(L"Trigger: %s\n",webhookEvent.stringOf(L"trigger"));
    //  Deduplicate using event.id, not BOX-DELIVERY-ID, which changes on retries.
    //  Verify the target belongs to your configured webhook before dispatching work.
    }