Dropbox webhook payload example (file change notification)

Dropbox · event: file change notification · content type: application/json

This is a representative sample — fake IDs, real structure. To see a payload with your data, point the provider at a capture URL (button below).

See it live, not frozen

One click creates a free capture bin with this exact payload already in it — pretty-printed, headers inspectable, replayable to your own endpoint:

Then paste the bin's URL into Dropbox's webhook settings to capture a real delivery. No signup.

Headers

content-type: application/json
x-dropbox-signature: 7a322d18ac5ea3f394bb056d0d58dc8f031653666dfa9d8db026109d7a23c51a

Body

{
  "list_folder": {
    "accounts": [
      "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
      "dbid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I"
    ]
  },
  "delta": {
    "users": [
      12345678,
      23456789
    ]
  }
}

Things that bite people

The payload names accounts, not files. A Dropbox notification is a thin ping: list_folder.accounts (scoped-app account IDs) and delta.users (legacy numeric IDs) tell you whose files changed — never what changed. You're expected to call /files/list_folder/continue with each user's stored cursor to fetch the actual changes. Handlers that look for file paths in this body find nothing.
Before any of this: the GET challenge handshake. When you add your webhook URI in the App Console, Dropbox sends a verification GET with a challenge query parameter that you must echo back — with Content-Type: text/plain and X-Content-Type-Options: nosniff (Dropbox's docs call the headers out to avoid a reflected-XSS hole). A capture bin passes this with zero code: set the response body to {{query.challenge}}, Content-Type text/plain, and add a response header line X-Content-Type-Options: nosniff. Failures show up as an error message in the App Console.
This example's signature actually verifies: X-Dropbox-Signature is bare hex HMAC-SHA256 of the raw body, key = your app secret — here the sample hookden_dropbox_sample_app_secret. Paste body + header into the signature debugger (generic scheme), or set the same secret on a capture bin (generic scheme, header x-dropbox-signature) for live ✓/✗ badges. Dropbox's docs say verifying is "a good idea (but not required)" — do it anyway; your endpoint is public.
Ten-second response deadline. Respond first, process async — Dropbox's own tutorial spawns a worker thread before returning. Remember list_folder backfills can be huge when a new user first links your app (their whole folder tree is "changed").
Silent no-events traps: webhooks only fire for accounts that have completed OAuth with your app — zero connected accounts = zero notifications, ever. Scoped apps also need files.metadata.read granted during the OAuth flow. And the URI must be publicly reachable — localhost/127.0.0.1 never work (that's the relay use case: webhooks to localhost).
Expect duplicate/overlapping pings for the same user in rapid succession — Dropbox recommends idempotent processing or per-user leases. The docs publish no retry schedule for failed notification deliveries — treat delivery as best-effort and rely on cursors: whenever the next ping arrives, list_folder/continue returns everything you missed.

Send it yourself

Reproduce this delivery against any endpoint (your handler, a bin, staging):

$ curl -X POST https://your-endpoint.example/hook \
  -H 'content-type: application/json' \
  -H 'x-dropbox-signature: 7a322d18ac5ea3f394bb056d0d58dc8f031653666dfa9d8db026109d7a23c51a' \
 -d '{
  "list_folder": {
    "accounts": [
      "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
      "dbid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I"
    ]
  },
  "delta": {
    "users": [
      12345678,
      23456789
    ]
  }
}'

← All payload examples · Signature debugger · Docs