Test Dropbox webhooks locally

Receive Dropbox notifications on your laptop while you build, with a public HTTPS URL Dropbox can reach.

Horizon has no Dropbox integration. Dropbox sends webhooks to a public URL, and Horizon provides that URL.

Before you beginCopy Anchor Link

• Node.js 18 or later
• A Horizon account and the CLI (see Getting started)
• A reserved subdomain for -s. Reserve one on the Subdomains page.
• A Dropbox app in the App Console
• At least one Dropbox account connected to the app through OAuth. Without a connected account, Dropbox sends no notifications. If your app is scoped, the user must authorize files.metadata.read.
• A Next.js app that uses the App Router and runs on port 3000

import { createHmac, timingSafeEqual } from "node:crypto";

export async function GET(request: Request) {
  const challenge = new URL(request.url).searchParams.get("challenge") ?? "";

  return new Response(challenge, {
    status: 200,
    headers: {
      "Content-Type": "text/plain",
      "X-Content-Type-Options": "nosniff",
    },
  });
}

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

  const body = await request.text();
  const received = request.headers.get("x-dropbox-signature") ?? "";
  const expected = createHmac("sha256", appSecret).update(body).digest("hex");

  const receivedBuffer = Buffer.from(received);
  const expectedBuffer = Buffer.from(expected);
  const isValid =
    receivedBuffer.length === expectedBuffer.length &&
    timingSafeEqual(receivedBuffer, expectedBuffer);

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

  const notification = JSON.parse(body);
  console.log("Dropbox accounts with changes:", notification.list_folder?.accounts);

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

DROPBOX_APP_SECRET=replace-with-your-app-secret

npm run dev

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

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

  GET     200  /api/webhooks/dropbox

Check it worksCopy Anchor Link

Change a file in the connected account. The Horizon terminal prints:

  POST    200  /api/webhooks/dropbox

Your app terminal prints the account IDs that changed:

Dropbox accounts with changes: [ 'dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc' ]

If the line shows [403], see Troubleshooting.

TroubleshootingCopy Anchor Link

The App Console shows a verification errorCopy Anchor Link

Dropbox's GET request failed. Check that the tunnel and npm run dev are running before you add the URI. Check that the URI ends with /api/webhooks/dropbox. Check that the handler returns the challenge unchanged, with Content-Type: text/plain and X-Content-Type-Options: nosniff.

The signature doesn't matchCopy Anchor Link

The Horizon line shows [403]. Check these in order:

• DROPBOX_APP_SECRET is the secret of the same app that holds the webhook. Restart npm run dev after you edit .env.local.
• The handler hashes the raw body from request.text(). Parsing and re-serializing the JSON changes the bytes.
• You compare against the hex digest, not Base64.

No notifications arriveCopy Anchor Link

• Check that at least one account is connected to the app. Dropbox sends no notifications for an app with no connected accounts.
• For a scoped app, check that the user authorized files.metadata.read.
• Change a file inside the folder scope your app can see.

The URL changed after a restartCopy Anchor Link

You started the tunnel without -s, so Horizon gave you a new random subdomain. Restart with -s my-dropbox-app. If the URL differs from the one in the App Console, add the new one.

Next stepsCopy Anchor Link

• Read Dropbox's webhooks documentation.
• Call /files/list_folder/continue to read the changes behind a notification.
• Reserve a subdomain so your URL never changes: see pricing.