Folder Webhooks

Receive files from external systems automatically in a specified folder. Each folder gets a unique receiving URL, and data sent to that URL is saved in the folder.

Before you begin

• An administrator must enable Workspace webhooks under Configure Webhook Policies.

Create a webhook in a folder

1. Select the settings (⚙️) icon next to the folder that will receive the webhook.
2. On the Automatic Receiving (Webhook) tab, select Add.
3. Select an authentication method and conflict policy. Both options are described below.
4. Select Create to generate the folder's unique receiving URL. If you selected Secure, a signing secret is also generated. These values are shown only once, so copy them to a secure location now.
5. Configure the external system using the receiving URL and example shown on screen. See "Select an authentication method" below for request examples.
6. A folder with a webhook displays the icon.

Select an authentication method

Select either Simple or Secure when creating a webhook.

A Simple webhook accepts requests using only its URL.

# Upload a file via multipart
curl -i -X POST "https://<receiving-url>?filename=photo.jpg" \
  -F "file=@./photo.jpg"

A Secure webhook signs a SHA-256 hash of the entire multipart request body, including boundaries and part headers.

# Upload a file via multipart (with HMAC signature)
TS=$(date +%s)
NONCE=$(cat /proc/sys/kernel/random/uuid)
BOUNDARY="------------------------$(cat /proc/sys/kernel/random/uuid)"
TMP=$(mktemp /tmp/multipart.XXXXXX)

# Build the raw multipart body first, then hash that body.
printf -- --%s$'\r\n' "$BOUNDARY" > "$TMP"
printf 'Content-Disposition: form-data; name="file"; filename="photo.jpg"' >> "$TMP"
printf $'\r\n' >> "$TMP"
printf 'Content-Type: application/octet-stream' >> "$TMP"
printf $'\r\n\r\n' >> "$TMP"
cat ./photo.jpg >> "$TMP"
printf $'\r\n' >> "$TMP"
printf -- --%s--$'\r\n' "$BOUNDARY" >> "$TMP"

BODY_SHA=$(sha256sum "$TMP" | awk '{print $1}')
SIG=$(printf 'POST\n<receiving-path>\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA" \
  | openssl dgst -sha256 -hmac "$SECRET" -binary | xxd -p -c 256)

curl -i -X POST "https://<receiving-url>?filename=photo.jpg" \
  -H "Content-Type: multipart/form-data; boundary=$BOUNDARY" \
  -H "X-Webhook-Timestamp: $TS" \
  -H "X-Webhook-Nonce: $NONCE" \
  -H "X-Webhook-Signature: sha256=$SIG" \
  --data-binary @"$TMP"

rm -f "$TMP"

Select a conflict policy

Choose how to handle a newly received file when another file has the same name. You can change the policy later on the same screen by selecting Apply.

Specify a filename

Specify the uploaded filename in either of these ways:

• Query parameter: ?filename=report.json
• HTTP header: X-Webhook-Filename: report.json

Review received data

Data sent from external systems accumulates as files in the folder. Open the folder to review received items.

Pause or delete a webhook

• In the folder, hover over a webhook in the list to display the pause and delete buttons.
• Open My Webhooks under Account Settings to see every folder where you configured a webhook. You can also pause or delete webhooks from this list.

Related documents

• Webhook Policy Settings