Webhooks

With webhooks, your web app can be notified when your users' files and datastores change, rather than requiring your app to frequently poll Dropbox for changes. Every time a user's files or datastores change, the webhook URI you specify will be sent an HTTP request telling it about the changes. You can register webhook URIs via the App Console. To learn more about how to use webhooks, read the webhooks tutorial.

Handling the verification request

The first request to your new webhook URI will be a verification request to confirm that Dropbox is communicating with the right service.

The verification request will be a GET request with a challenge parameter, which is a random string (e.g. https://www.example.com/dropbox-webhook?challenge=abc123). Your app should echo back the challenge parameter as the body of its response. Once Dropbox receives a valid response, the endpoint is considered to be a valid webhook, and Dropbox will begin sending notifications of file changes. Your app has up to ten seconds to respond to the verification request. Dropbox will not perform automatic retry for verification requests.

Receiving notifications

Once you have successfully added your webhook endpoint, Dropbox will begin sending POST requests to your webhook endpoint when any user linked to the app has a file change. If multiple users make changes at the same time, they may be included in the same notification.

You can verify the authenticity of the request by looking at the X-Dropbox-Signature header, which will contain the HMAC-SHA256 signature of the entire request body using your app secret as the key.

When sending change notifications to your app, Dropbox will handle errors with exponential backoff. Each request that results in a non-200 response code or times out will be re-attempted over the course of about ten minutes. After that, a failure will be reported, which you'll be able to see in the App Console.

The body of the HTTP request will be JSON with details about the changes.

File notifications

For file changes, your endpoint will receive JSON with the following format:

{
  "delta": {
    "users": [
      12345678,
      23456789,
      ...
    ]
  }
}

Note that only the user IDs with file changes are provided. Your app is expected to call /delta to find out what files changed.

Datastore notifications

For datastore changes, your endpoint will receive JSON with the following format:

{
    "datastore_delta": [
        {
            "handle": "abc123",
            "dsid": "default",
            "change_type": "update",
            "owner": 12345678,
            "updater": 23456789
        },
        {
            "handle": "456xyz",
            ...
        },
        ...
    ]
}

The following datastore change_types are defined:

• update – The contents of the datastore changed. (I.e. records were inserted, deleted, or modified.)
• create – The datastore was created.
• delete – The datastore was deleted.

Dropbox for Business notifications

There are also webhooks for the Dropbox for Business API. Find out more about Dropbox for Business API webhooks.

More information

To see an example of working with webhooks, check out the webhooks tutorial.