웹훅

원문 보기 위키 갱신 2026.10.11

웹훅 (Webhooks)

Webhook은 설정된 URL로 HTTP POST 요청을 보내는 훅 타입이에요. 응답 엔드포인트가 2XX가 아닌 응답을 보내면 훅이 실패하고, 같은 액션 아래의 이후 훅 실행이 취소돼요. pre-* 훅이라면 트리거된 작업 자체도 중단돼요.

경고

pre-* 웹훅으로 오래 걸리는 작업을 하면 안 돼요. 진행 중인 작업을 막기 때문이에요. 게다가 pre-* 훅이 실행되는 동안 브랜치가 잠기기 때문에, 웹훅 서버가 그 브랜치에 쓰기 작업(업로드나 커밋 등)을 수행할 수도 없어요.

출처: 문서

본문

웹훅 목적지 제한하기

훅이 연결할 수 있는 곳을 제한하려면 actions.network.blocked_addresses 설정 아래에 차단할 IP 주소나 CIDR 범위를 나열하세요:

actions:
  network:
    blocked_addresses: ["169.254.169.254", "10.0.0.0/8"]

차단된 주소는 리다이렉트를 포함한 모든 연결에 적용되고, 훅 요청은 프록시 환경 변수를 쓰지 않고 직접 연결해요.

액션 파일의 Webhook 속성

전체 설정 스키마와 세부 사항은 Action configuration을 참고하세요.

속성	설명	데이터 타입	필수	기본값	환경 변수 지원
url	요청의 URL 주소	String	true		no
timeout	훅을 실패 처리하기 전에 응답을 기다릴 시간	String (golang's Duration representation)	false	1 minute	no
query_params	요청에 추가할 쿼리 파라미터 목록	Dictionary(String:String or String:List(String)	false		yes
headers	요청에 추가할 헤더	Dictionary(String:String)	false		yes

시크릿과 환경 변수

lakeFS Actions는 환경 변수로 시크릿을 지원해요. {% raw %}{{{% endraw %} ENV.SOME_ENV_VAR {% raw %}}}{% endraw %} 형식은 액션이 실행되는 동안 $SOME_ENV_VAR의 값으로 치환돼요. 그 환경 변수가 lakeFS 서버 환경에 존재하지 않으면 액션 실행이 실패해요.

정보

모든 환경 변수는 "LAKEFSACTIONS_"로 시작해야 해요. 그렇지 않으면 차단돼요. 또한 actions.env.enabled 설정 파라미터를 false로 두면 모든 환경 변수 접근을 막을 수 있어요.

예시

...
hooks:
- id: prevent_user_columns
    type: webhook
    description: Ensure no user_* columns under public/
    properties:
    url: "http://<host:port>/webhooks/schema"
    timeout: 1m30s
    query_params:
        disallow: ["user_", "private_"]
        prefix: public/
    headers:
        secret_header: "{% raw %}{{{% endraw %} ENV.MY_SECRET {% raw %}}}{% endraw %}"
...

요청 본문 스키마

웹훅은 실행될 때 다음 필드를 담은 JSON 객체를 요청으로 보내요:

필드	설명	타입
event_type	액션을 트리거한 이벤트의 타입	string
event_time	액션을 트리거한 이벤트의 시각 (RFC3339 형식)	string
action_name	이 훅이 속한 액션의 이름	string
hook_id	훅의 ID	string
repository_id	저장소의 ID	string
branch_id1	브랜치의 ID	string
source_ref	이벤트가 트리거된 소스 참조	string
commit_message2	진행 중인 커밋(또는 머지)의 메시지	string
committer2	커미터 이름	string
commit_metadata2	진행 중인 커밋의 메타데이터	string
commit_id3	생성 중인 커밋의 ID	string
tag_id	생성/삭제된 태그의 ID (태그 이벤트에서 제공)	string
merge_source	머지 시 소스 브랜치/태그/ref (머지 이벤트에서 제공)	string

예시

{
    "event_type": "pre-merge",
    "event_time": "2021-02-28T14:03:31Z",
    "action_name": "test action",
    "hook_id": "prevent_user_columns",
    "repository_id": "repo1",
    "branch_id": "feature-1",
    "source_ref": "feature-1",
    "commit_message": "merge commit message",
    "commit_id": "5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03",
    "committer": "committer",
    "commit_metadata": {
        "key": "value"
    }
}

태그 이벤트에는 해당 없음 ↩
태그 이벤트와 브랜치 생성/삭제 이벤트에는 해당 없음 ↩↩↩
커밋/머지 이벤트에서만 제공돼요. 머지에서는 머지가 성공할 경우 생성될 머지 커밋 ID를 의미해요. ↩

더 알아보기 (Learn more)

공식 문서: lakeFS Webhooks 가이드