Dropbox webhooks
Last verified against Dropbox's documentation on September 27, 2026.
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
| Behavior | Detail |
|---|---|
| Verification | A GET with a challenge query parameter. Echo it as the response body within 10 seconds. Not retried |
| Method and format | POST with a JSON body |
| Signature header | X-Dropbox-Signature: hex HMAC-SHA256 of the body, keyed with your app secret |
| Response window | 10 seconds |
| Failures | Retried 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-Signaturewon’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
- In HookDeploy, create an endpoint (for example,
Dropbox notifications) and copy its URL. - On the endpoint’s Security tab, under Verification, choose Dropbox and save (Starter and above).
- On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
- In the Dropbox App Console, open your app’s settings and add your HookDeploy URL under Webhooks. Dropbox sends the challenge, and HookDeploy answers.
- 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.