Dropbox Trigger

Triggers a workflow when files change in the Dropbox account a connection is authorized for.

Dropbox webhook URLs are configured at the App level in the Dropbox App Console, not via an API call — Dropbox does not expose a programmatic endpoint to register webhook URIs. You paste the URL into the App Console once per app, and every workflow built on that connection receives deliveries.

Requires a Dropbox connection configured with the App Secret (used for signature verification).

Webhook URL is per-connection, not per-workflow

Unlike webhook trigger URLs that are scoped to a single workflow, the Dropbox URL is scoped to the connection. It looks like:

https://<your-deployment>/api/conn-webhook/<connection-webhook-token>

<connection-webhook-token> is generated when you create the Dropbox connection and stored in connection.metadata.webhook_token. You can read it with:

curl -H "Authorization: Bearer $TOKEN" \
  https://<your-deployment>/api/connections/<connection-id> \
  | jq '.data.metadata.webhook_token'

The same URL services every dropbox_trigger workflow that references this connection — the dispatcher fans the delivery out to all matching workflows.

Setup

1. Create the Dropbox connection and copy its webhook URL from metadata.webhook_token.
2. Open your Dropbox App at dropbox.com/developers/apps → Webhooks tab.
3. Paste the URL into Webhook URIs and click Add. Dropbox immediately sends a one-time GET <url>?challenge=<random> to verify ownership — the backend echoes the challenge automatically.
4. Confirm the entry shows Enabled in the App Console. If it flips to disabled, the public URL was unreachable at that moment (tunnel down, deploy mid-flight); re-add it once the deployment is healthy.
5. Build a workflow with the Dropbox Trigger as the first node, set its Connection to the connection above, and publish.

Output

Dropbox webhooks deliver a change ping — the POST body announces "user X has changes," not the actual file deltas. The trigger output looks like:

{
  "body": {
    "list_folder": { "accounts": ["dbid:AAH..."] },
    "delta":       { "users":    [12345] }
  }
}

To list what actually changed, call Dropbox's /2/files/list_folder/continue for each account in body.list_folder.accounts. You'll need a cursor — get the initial one with POST /2/files/list_folder on first run and persist it (e.g. in the workflow's datastore).

Field	Description
body.list_folder.accounts	Array of Dropbox account IDs that had changes
body.delta.users	For team apps, array of team member IDs that had changes
headers.X-Dropbox-Signature	HMAC-SHA256 signature (already verified before the workflow runs)

How it works

• Every POST is verified with HMAC-SHA256(app_secret, raw_body) in hex, compared to the X-Dropbox-Signature header. The driver uses the connection's stored App Secret — the trigger refuses to dispatch if the verification fails.
• The initial GET …?challenge=<token> from Dropbox is handled by the dispatcher before signature checks. The challenge is echoed as text/plain.
• ParseEventType always returns "change" — Dropbox doesn't tag deliveries with event subtypes. Set the trigger's Events filter to ["change"] or ["*"].

App Secret required

The Dropbox Trigger refuses to publish if the connection is missing its App Secret. Without it, deliveries cannot be authenticated.

Dropbox doesn't expose a registration API

This is intentional on Dropbox's side — webhook URIs are part of an app's configuration, and Dropbox doesn't allow programmatic mutation of app settings. The App Console is the only path. See the Dropbox webhook reference.