폴더 웹훅

외부 시스템이 보낸 파일을 지정한 폴더에 자동으로 저장합니다. 폴더마다 고유한 수신 주소가 만들어지고, 외부에서 이 주소로 파일을 보내면 폴더에 저장됩니다.

시작하기 전에

• 관리자 설정: 웹훅 정책 설정하기에서 인바운드 웹훅 기능 사용과 사용자 API 키 발급 허용을 모두 켜야 합니다.

폴더에 웹훅 만들기

1. 웹훅을 받을 폴더의 이름 옆 설정(⚙️) 아이콘을 선택합니다.
2. 웹훅 수신 탭에서 추가 버튼을 선택합니다.
3. 인증 방식과 충돌 정책을 선택합니다. 각 항목은 아래에서 설명합니다.
4. 생성을 선택하면 폴더 고유의 수신 주소(Endpoint URL)가 만들어집니다. Secure를 선택했다면 서명 비밀값(signing secret)도 함께 만들어집니다. 이 값은 지금만 표시되므로 안전한 곳에 복사해 둡니다.
5. 화면에 표시된 수신 주소와 예시를 참고해 외부 시스템에서 웹훅을 설정합니다. 인증 방식별 요청 예시는 아래 인증 방식 선택하기를 참고합니다.
6. 웹훅을 설정한 폴더에는 아이콘이 표시됩니다.

인증 방식 선택하기

웹훅을 만들 때 Simple과 Secure 중 하나를 선택합니다.

Simple로 만든 웹훅은 URL만으로 요청을 보낼 수 있습니다.

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

Secure로 만든 웹훅은 요청 본문의 SHA-256 해시를 서명에 포함해야 합니다. 해시는 경계와 파트 헤더를 포함한 멀티파트 본문 전체로 계산합니다.

# 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<수신 경로>\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://<수신 주소>?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"

충돌 정책 선택하기

같은 이름의 파일을 받았을 때 처리할 방법을 정합니다. 웹훅을 만들 때 선택하며, 만든 뒤에도 같은 화면에서 바꾸고 적용을 선택할 수 있습니다.

파일명 지정하기

파일 이름은 다음 두 가지 방법 중 하나로 지정합니다.

• 쿼리 파라미터: ?filename=report.json
• HTTP 헤더: X-Webhook-Filename: report.json

하위 폴더에 저장하기

웹훅으로 받은 파일은 웹훅을 만든 폴더에 저장됩니다. 파일명에 하위 경로를 붙여 하위 폴더에 저장하려면 웹훅의 하위 폴더 저장을 켭니다.

1. 웹훅 목록에서 설정할 웹훅을 펼칩니다.
2. 하위 폴더 저장에서 허용을 선택합니다.
3. 적용을 선택합니다.

파일명에는 웹훅 폴더 기준의 상대 경로를 지정합니다. 없는 폴더는 자동으로 만들어집니다.

• 쿼리 파라미터: ?filename=releases/1.0/a.zip
• HTTP 헤더: X-Webhook-Filename: releases/1.0/a.zip

받은 데이터 확인

외부에서 보낸 파일은 폴더에 쌓입니다. 폴더를 열어 받은 파일을 확인합니다.

웹훅 일시중지 및 삭제

• 웹훅 목록에서 웹훅에 마우스를 올리면 일시중지·삭제 버튼이 나타납니다.
• 계정 설정의 내 웹훅에서 내가 웹훅을 설정한 폴더를 모아 보고, 일시중지하거나 삭제할 수 있습니다.

관련 문서

• 웹훅 설정