# Dropbox Webhooks

These are webhooks for **Dropbox API apps** (file and folder changes), not Dropbox Sign.

## When to Use This Skill

* How do I receive Dropbox webhooks?
* How do I answer the Dropbox webhook `challenge` verification request?
* How do I verify the `X-Dropbox-Signature` header?
* How do I find out what changed after a Dropbox `list_folder` notification?
* Why is my Dropbox webhook URI failing verification or signature checks?

## How Dropbox Webhooks Work

Dropbox webhooks are **change pings**, not event payloads. A notification lists the account IDs that have changes; you then call the API (`/files/list_folder/continue` with your saved cursor) to get the actual file changes. There is no event-type field or header.

1. **Verification request** — when you add the URI in the App Console (and periodically after), Dropbox sends `GET <uri>?challenge=<random>`. Reply `200` echoing the value with `Content-Type: text/plain` and `X-Content-Type-Options: nosniff`.
2. **Notification** — `POST` with JSON body and an `X-Dropbox-Signature` header.

## Verification (core)

`X-Dropbox-Signature` is the **hex** HMAC-SHA256 of the **raw request body**, keyed with your app secret (the "App secret" in the App Console). No timestamp, no prefix. Compare timing-safe.

Node:

```javascript
const crypto = require('crypto');

function verify(rawBody, signature, appSecret) {
  if (!signature) return false;
  const expected = crypto.createHmac('sha256', appSecret).update(rawBody).digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false; // different lengths
  }
}

// GET challenge: res.set({ 'Content-Type': 'text/plain', 'X-Content-Type-Options': 'nosniff' }).send(req.query.challenge)

```

Python:

```python
import hmac, hashlib

def verify(raw_body: bytes, signature: str, app_secret: str) -> bool:
    if not signature:
        return False
    expected = hmac.new(app_secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

```

> **For complete handlers with route wiring, challenge handling, and tests**, see:
> 
> * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/dropbox-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/dropbox-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/dropbox-webhooks/examples/fastapi/)

## Notification Payload

Dropbox has no named event types. The body contains these top-level keys:

| Key | Description |
| --- | --- |
| `list_folder.accounts` | Account IDs with file changes. Call `/files/list_folder/continue` with the stored cursor for each |
| `delta.users` | Legacy user IDs (deprecated `/delta` API) |

```json
{"list_folder": {"accounts": ["dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"]}, "delta": {"users": [12345678]}}

```

Respond `200` quickly (Dropbox expects a response within 10 seconds) and do the `list_folder/continue` work asynchronously.

## Important Headers

| Header | Description |
| --- | --- |
| `X-Dropbox-Signature` | Hex HMAC-SHA256 of the raw body, keyed with the app secret |

## Environment Variables

```bash
DROPBOX_APP_SECRET=your_app_secret   # App Console > Settings > App secret

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 dropbox --path /webhooks/dropbox

```

Use the Hookdeck URL as the webhook URI in the App Console; Dropbox's challenge request is forwarded to your local server.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/dropbox-webhooks/references/overview.md) - Dropbox webhook concepts and payload
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/dropbox-webhooks/references/setup.md) - App Console configuration
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/dropbox-webhooks/references/verification.md) - Challenge and signature verification details