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

Zig

const std = @import("std");
const chilkat = @import("chilkat");

pub fn main(init: std.process.Init) !void {
    const alloc = init.arena.allocator();

    var success: bool = 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.
    const raw_body = try chilkat.BinData.init();
    defer raw_body.deinit();
    raw_body.loadFile("qa_data/box_webhook_body.bin") catch {
        std.debug.print("{s}\n", .{try raw_body.getLastErrorText(alloc)});
        return;
    };

    // Read these fields case-insensitively from the incoming request headers.
    // For this offline example, enter the captured header values.
    const timestamp = "BOX_DELIVERY_TIMESTAMP";
    const primary_signature = "BOX_SIGNATURE_PRIMARY";
    const secondary_signature = "BOX_SIGNATURE_SECONDARY";
    const signature_version = "1";
    const signature_algorithm = "HmacSHA256";
    // Retrieve configured keys from protected application configuration.
    const primary_key = "BOX_PRIMARY_SIGNATURE_KEY";
    const secondary_key = "BOX_SECONDARY_SIGNATURE_KEY";
    if ((!std.mem.eql(u8, signature_version, "1")) or (!std.mem.eql(u8, signature_algorithm, "HmacSHA256"))) {
        std.debug.print("Unsupported signature version or algorithm.\n", .{});
        return;
    }

    const delivered = try chilkat.DateTime.init();
    defer delivered.deinit();
    delivered.setFromTimestamp(timestamp) catch {
        std.debug.print("{s}\n", .{try delivered.getLastErrorText(alloc)});
        return;
    };

    const now = try chilkat.DateTime.init();
    defer now.deinit();
    now.setFromCurrentSystemTime() catch {
        std.debug.print("{s}\n", .{try now.getLastErrorText(alloc)});
        return;
    };

    const age = @as(i32, @intCast(now.getAsUnixTime(false))) - @as(i32, @intCast(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)) {
        std.debug.print("Delivery timestamp is outside the accepted window.\n", .{});
        return;
    }

    const signed_bytes = try chilkat.BinData.init();
    defer signed_bytes.deinit();
    signed_bytes.appendBd(raw_body) catch {
        std.debug.print("{s}\n", .{try signed_bytes.getLastErrorText(alloc)});
        return;
    };

    signed_bytes.appendString(timestamp, "utf-8") catch {
        std.debug.print("{s}\n", .{try signed_bytes.getLastErrorText(alloc)});
        return;
    };

    const mac = try chilkat.Crypt2.init();
    defer mac.deinit();
    mac.setMacAlgorithm("hmac");
    mac.setHashAlgorithm("sha256");
    mac.setEncodingMode("base64");
    mac.setMacKeyString(primary_key) catch {
        std.debug.print("{s}\n", .{try mac.getLastErrorText(alloc)});
        return;
    };

    const expected_primary = mac.macBdENC(alloc, signed_bytes) catch {
        std.debug.print("{s}\n", .{try mac.getLastErrorText(alloc)});
        return;
    };

    mac.setMacKeyString(secondary_key) catch {
        std.debug.print("{s}\n", .{try mac.getLastErrorText(alloc)});
        return;
    };

    const expected_secondary = mac.macBdENC(alloc, signed_bytes) catch {
        std.debug.print("{s}\n", .{try mac.getLastErrorText(alloc)});
        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.
    const random = try chilkat.Prng.init();
    defer random.deinit();
    const comparison_key = random.genRandom(alloc, 32, "base64") catch {
        std.debug.print("{s}\n", .{try random.getLastErrorText(alloc)});
        return;
    };

    mac.setMacKeyEncoded(comparison_key, "base64") catch {
        std.debug.print("{s}\n", .{try mac.getLastErrorText(alloc)});
        return;
    };

    const p_expected = mac.macStringENC(alloc, expected_primary) catch {
        std.debug.print("{s}\n", .{try mac.getLastErrorText(alloc)});
        return;
    };

    const p_received = mac.macStringENC(alloc, primary_signature) catch {
        std.debug.print("{s}\n", .{try mac.getLastErrorText(alloc)});
        return;
    };

    const s_expected = mac.macStringENC(alloc, expected_secondary) catch {
        std.debug.print("{s}\n", .{try mac.getLastErrorText(alloc)});
        return;
    };

    const s_received = mac.macStringENC(alloc, secondary_signature) catch {
        std.debug.print("{s}\n", .{try mac.getLastErrorText(alloc)});
        return;
    };

    const valid_primary = (!std.mem.eql(u8, primary_key, "")) and ((!std.mem.eql(u8, primary_signature, "")) and (std.mem.eql(u8, p_expected, p_received)));
    const valid_secondary = (!std.mem.eql(u8, secondary_key, "")) and ((!std.mem.eql(u8, secondary_signature, "")) and (std.mem.eql(u8, s_expected, s_received)));
    if ((!valid_primary) and (!valid_secondary)) {
        std.debug.print("Signature verification failed.\n", .{});
        return;
    }

    // Parse JSON only after signature verification.
    const webhook_event = try chilkat.JsonObject.init();
    defer webhook_event.deinit();
    webhook_event.load(try raw_body.getString(alloc, "utf-8")) catch {
        std.debug.print("{s}\n", .{try webhook_event.getLastErrorText(alloc)});
        return;
    };

    std.debug.print("Verified event ID: {s}\n", .{try webhook_event.stringOf(alloc, "id")});
    std.debug.print("Trigger: {s}\n", .{try webhook_event.stringOf(alloc, "trigger")});
    // Deduplicate using event.id, not BOX-DELIVERY-ID, which changes on retries.
    // Verify the target belongs to your configured webhook before dispatching work.
}