Test Box webhooks locally

Start your appCopy Anchor Link

Box signs every V2 webhook with up to two keys, a primary and a secondary. Two keys let you rotate one without downtime. Box computes an HMAC-SHA256 (a keyed hash) over the raw body followed by the BOX-DELIVERY-TIMESTAMP value, encodes it as Base64, and sends it in BOX-SIGNATURE-PRIMARY and BOX-SIGNATURE-SECONDARY. A delivery is valid when at least one signature matches.

The official Box Node SDK ships a helper that does the whole check, including the timestamp. Install it:

npm install box-node-sdk

Create the route handler. Read the raw body with request.text(). Don't parse it first, because the signature covers the exact bytes.

import { WebhooksManager } from "box-node-sdk/managers";

export async function POST(request: Request) {
  const primaryKey = process.env.BOX_PRIMARY_KEY;
  if (!primaryKey) {
    return new Response("Missing BOX_PRIMARY_KEY", { status: 500 });
  }

  const body = await request.text();
  const headers = Object.fromEntries(request.headers);

  const isValid = await WebhooksManager.validateMessage(body, headers, primaryKey, {
    secondaryKey: process.env.BOX_SECONDARY_KEY,
  });

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const event = JSON.parse(body);
  console.log(`Received Box event: ${event.trigger}`);

  return new Response("ok", { status: 200 });
}

validateMessage rejects a delivery whose BOX-DELIVERY-TIMESTAMP is older than ten minutes, which is the limit Box documents.

Box wants a 2xx response within 30 seconds. Keep the handler fast.

You get the keys in the next steps. Add them to .env.local once you have them:

BOX_PRIMARY_KEY=replace-with-your-primary-key
BOX_SECONDARY_KEY=replace-with-your-secondary-key

Start the app:

npm run dev

Start a tunnelCopy Anchor Link

In a second terminal, open a tunnel to port 3000 on a subdomain you reserved, with -s:

hrzn tunnel http://localhost:3000 -s my-box-app

HORIZON: Tunnel connected
  URL          https://my-box-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-box-app

Your public URL is https://my-box-app.hrzn.run. Without -s the subdomain is random and changes on every run, so the URL you give Box would stop working after a restart. Reserved subdomains are a paid feature, see Pricing.

Generate the signature keysCopy Anchor Link

1. Open your application in the Developer Console.
2. Select the Webhooks tab.
3. Select Manage signature keys.
4. Select Generate Key to create the primary key. Generate the secondary key the same way.
5. Copy both values into .env.local as BOX_PRIMARY_KEY and BOX_SECONDARY_KEY, then restart npm run dev.

Without signature keys, Box sends no signature headers and the handler rejects every request.

Create the webhook in BoxCopy Anchor Link

Your endpoint URL is the tunnel URL plus the route path: https://my-box-app.hrzn.run/api/webhooks/box. Box requires an HTTPS URL.

1. Open your application in the Developer Console and select the Webhooks tab.
2. Select Create webhook.
3. Select V2 from the drop-down list.
4. Enter the endpoint URL in URL Address.
5. Set Content type to the kind of item to watch, a file or a folder, and choose that item.
6. Select the Triggers you want, for example FILE.UPLOADED.
7. Select Create webhook to save.

Trigger an eventCopy Anchor Link

Box has no resend button for V2 webhooks. Do the thing the trigger watches for. For FILE.UPLOADED on a folder, upload a file to that folder in Box. Box then sends a new delivery to your endpoint.