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 turn on both Enable Inbound Webhooks and Allow User API Key Issuance 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 Webhook inbound 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 (Endpoint URL). If you selected Secure, a Signature Secret (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

Save into subfolders

Files received through a webhook are saved directly in the folder where the webhook was created. To save them into subfolders of that folder by adding a sub path to the file name, turn on Subfolders for the webhook.

1. Expand the webhook you want to set in the webhook list.
2. Select Allowed under Subfolders.
3. Select Apply.

In the file name, specify a path relative to the webhook folder. Missing folders are created automatically.

• Query parameter: ?filename=releases/1.0/a.zip
• HTTP header: X-Webhook-Filename: releases/1.0/a.zip

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, you can pause or delete a webhook. Hover over a webhook in the list to display the Pause and Delete buttons.
• Open the My Webhooks tab 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 Settings