Skip to content
HookDeploy

Dropbox webhooks

Last verified against Dropbox's documentation on September 27, 2026.

On this page ↓

Dropbox sends webhooks when files change for any user linked to your app. They’re deliberately thin: a notification lists which accounts have changes, and your app calls Dropbox’s API to find out what changed. Before any of that, your URL has to pass a one-time challenge, which Dropbox never retries. This page covers what Dropbox sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What Dropbox sends webhooks for

Each notification is a JSON POST listing the accounts with changes:

{ "list_folder": { "accounts": ["dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"] } }

Several users’ changes can arrive in one notification. For each account, call /files/list_folder/continue with that user’s cursor to get the actual changes.

How Dropbox delivers webhooks

BehaviorDetail
VerificationA GET with a challenge query parameter. Echo it as the response body within 10 seconds. Not retried
Method and formatPOST with a JSON body
Signature headerX-Dropbox-Signature: hex HMAC-SHA256 of the body, keyed with your app secret
Response window10 seconds
FailuresRetried with exponential backoff

Common Dropbox webhook errors and how to fix them

Webhook URL won’t verify

Dropbox sends the challenge once and doesn’t retry it. Return the challenge value as the body, with a 200, within 10 seconds, then try adding the URL again.

Notification has no file details

That’s by design. Notifications only list account IDs. Call /files/list_folder/continue with each user’s stored cursor.

Timeouts

Calling Dropbox’s API for every account before responding can take longer than 10 seconds. Respond first, then process from a queue.

Signature doesn’t match

Hash the raw body with your app secret, not an access token, and compare against the hex header.

Why use HookDeploy with Dropbox

Capture every notification

HookDeploy captures every Dropbox webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. Dropbox gets its 200 right away, so slow processing never causes timeouts or retries.

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
  • History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.

Pass the challenge without code

Turn on the Dropbox handshake preset on the endpoint’s Security tab, under Verification (Starter and above). HookDeploy returns the challenge as plain text with the X-Content-Type-Options: nosniff header Dropbox asks for, and doesn’t capture it.

One webhook, many systems

Send each Dropbox event to your app, a reporting database, and a team channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Deliver to systems Dropbox can’t reach

The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so an internal tool or database in a private network can receive Dropbox events with no public endpoint.

Develop against real events

A tap sends a temporary copy of live Dropbox events to 127.0.0.1 on your machine while production keeps receiving them.

Know the limits

  • Transformations. A transformation changes the body, and then X-Dropbox-Signature won’t verify at that destination.
  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which Dropbox treats as a failed delivery. Paid plans keep accepting traffic past the included volume.

Retries, replays, and duplicates

Dropbox’s signature covers only the body, with no timestamp, and HookDeploy forwards the body and X-Dropbox-Signature header unchanged, so retries and replays verify like the original delivery.

Notifications only name accounts, and your handler fetches changes with each user’s cursor, so processing the same notification twice is harmless: the second fetch just finds nothing new.

The handshake preset runs after HookDeploy’s token check, so if your endpoint requires a token, register the webhook URL with ?token= added. HookDeploy removes it before forwarding.

Set up Dropbox with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Dropbox notifications) and copy its URL.
  2. On the endpoint’s Security tab, under Verification, choose Dropbox and save (Starter and above).
  3. On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
  4. In the Dropbox App Console, open your app’s settings and add your HookDeploy URL under Webhooks. Dropbox sends the challenge, and HookDeploy answers.
  5. Change a file for a linked account, and confirm the notification appears in HookDeploy and reaches your handler.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/dropbox', express.raw({ type: 'application/json' }), async (req, res) => {
  const expected = crypto
    .createHmac('sha256', process.env.DROPBOX_APP_SECRET)
    .update(req.body)
    .digest('hex');
  const received = req.get('x-dropbox-signature') ?? '';
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(403).send('Invalid signature');

  res.sendStatus(200);
  const { list_folder } = JSON.parse(req.body.toString('utf8'));
  for (const account of list_folder?.accounts ?? []) {
    await enqueue({ account });  // the worker calls /files/list_folder/continue with this user's cursor
  }
});

FAQ

How do I verify a Dropbox webhook URL?

Dropbox sends a GET request with a challenge query parameter, and your URL must return that value as the response body within 10 seconds. Dropbox doesn't retry it. With HookDeploy, the Dropbox handshake preset answers it for you.

How do I verify a Dropbox webhook notification?

Compute a hex HMAC-SHA256 of the raw request body using your app secret, and compare it to the X-Dropbox-Signature header.

Why doesn't the Dropbox webhook say which files changed?

Notifications only list the accounts with changes. Call /files/list_folder/continue with each user's cursor to get the changes.

How fast must I respond to Dropbox?

Within 10 seconds. Respond first and process from a queue.

Does Dropbox retry failed notifications?

Yes. Dropbox retries failed notifications with exponential backoff. The initial verification challenge isn't retried.

Does HookDeploy break Dropbox signature verification?

No. The signature covers only the body, and HookDeploy forwards the body and X-Dropbox-Signature header unchanged, so first deliveries, retries, and replays all verify.

Capture Dropbox webhooks free

Start free