Webhooks

Webhooks는 MLOps 관련 기능의 기반입니다. 특정 저장소 또는 특정 사용자/조직에 속한 모든 저장소(본인의 저장소뿐만 아니라 어떤 저장소든)의 새로운 변경 사항을 수신할 수 있습니다.

모델의 자동 변환, 커뮤니티 봇 구축, 모델/데이터셋/Spaces/버킷에 대한 CI/CD 구축 등에 사용할 수 있습니다(그 외 다양한 용도). Webhooks는 리포지토리 이벤트에 반응하여 계산 작업을 자동화하기 위해 Jobs를 트리거할 수도 있습니다.

Webhooks에 대한 문서가 아래에 있습니다. 또는 Webhooks의 몇 가지 가능한 사용 사례를 보여주는 가이드를 둘러보실 수도 있습니다:

• 데이터셋이 업데이트될 때마다 새 모델을 파인튜닝합니다 (Python)
• LLM API를 사용하여 Hub에 토론 봇 만들기 (NodeJS)
• 메타데이터 품질 보고서 생성 (Python)
• Jobs(CLI)를 사용하여 버킷의 새 파일 처리
• 그리고 더 많은 것이 추가될 예정입니다…

Webhook 생성

Webhooks 설정에서 새 Webhook을 생성하고 기존 Webhook을 편집할 수 있습니다:

Webhooks는 저장소 업데이트, Pull Requests, 토론, 새 댓글을 감시할 수 있습니다. Webhooks에 반응하는 Space를 만드는 것도 가능합니다!

Webhook 페이로드

Webhook을 등록하면 지정된 대상 URL에 HTTP POST 호출을 통해 새 이벤트에 대한 알림을 받게 됩니다. 페이로드는 JSON으로 인코딩됩니다.

webhook 설정 페이지의 활동 탭에서 전송된 페이로드의 이력을 볼 수 있으며, 디버깅을 쉽게 하기 위해 과거의 webhook을 다시 실행할 수도 있습니다:

예를 들어, Pull Request가 열릴 때의 전체 페이로드는 다음과 같습니다:

{
  "event": {
    "action": "create",
    "scope": "discussion"
  },
  "repo": {
    "type": "model",
    "name": "openai-community/gpt2",
    "id": "621ffdc036468d709f17434d",
    "private": false,
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2",
      "api": "https://huggingface.co/api/models/openai-community/gpt2"
    },
    "owner": {
      "id": "628b753283ef59b5be89e937"
    }
  },
  "discussion": {
    "id": "6399f58518721fdd27fc9ca9",
    "title": "Update co2 emissions",
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2/discussions/19",
      "api": "https://huggingface.co/api/models/openai-community/gpt2/discussions/19"
    },
    "status": "open",
    "author": {
      "id": "61d2f90c3c2083e1c08af22d"
    },
    "num": 19,
    "isPullRequest": true,
    "changes": {
      "base": "refs/heads/main"
    }
  },
  "comment": {
    "id": "6399f58518721fdd27fc9caa",
    "author": {
      "id": "61d2f90c3c2083e1c08af22d"
    },
    "content": "Add co2 emissions information to the model card",
    "hidden": false,
    // Note: when `hidden` is `true`, `content` will be undefined
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2/discussions/19#6399f58518721fdd27fc9caa"
    }
  },
  "webhook": {
    "id": "6390e855e30d9209411de93b",
    "version": 3
  }
}

이벤트

최상위 속성 event은 항상 지정되며 이벤트의 성격을 결정하는 데 사용됩니다.

두 개의 하위 속성이 있습니다: event.action와 event.scope입니다.

event.scope는 다음 값 중 하나가 됩니다:

• "repo" - 저장소 전역 이벤트. 관련 action의 가능한 값: "create", "delete", "update", "move".
• "repo.content" - 저장소의 콘텐츠에 대한 이벤트로, 새로운 커밋이나 태그 등이 해당됩니다. 새로 생성된 참조/커밋으로 인해 새로운 Pull Request에서도 트리거됩니다. Buckets의 경우 Git refs가 아니라 파일이 추가되거나 삭제될 때 트리거됩니다. 관련 action은 항상 "update"입니다.
• "repo.config" - config에 대한 이벤트: Space secrets 업데이트, 설정 업데이트, DOI 업데이트, 비활성화 여부 등. 관련 action은 항상 "update"입니다.
• "discussion" - 토론 또는 Pull Request 생성, 제목 또는 상태 업데이트, 병합. 관련 action의 가능한 값: "create", "delete", "update".
• "discussion.comment" - 댓글 생성, 업데이트 및 숨김. 관련 action의 가능한 값: "create", "update".

향후 더 많은 스코프가 추가될 수 있습니다. 알려지지 않은 이벤트를 처리하려면, 웹훅 핸들러는 좁혀진 스코프에 대한 모든 작업을 더 넓은 스코프에 대한 "update" 작업으로 간주할 수 있습니다.

예를 들어, 향후 "repo.config.dois" 스코프가 추가되면, 해당 스코프를 가진 모든 이벤트는 웹훅 핸들러에서 "repo.config" 스코프에 대한 "update" 액션으로 간주될 수 있습니다.

리포지토리

webhooks의 현재 버전에서는 이벤트가 항상 저장소와 연관될 수 있으므로 최상위 속성 repo는 항상 지정됩니다. 예를 들어, 다음 값을 고려해 보겠습니다:

"repo": {
	"type": "model",
	"name": "some-user/some-repo",
	"id": "6366c000a2abcdf2fd69a080",
	"private": false,
	"url": {
		"web": "https://huggingface.co/some-user/some-repo",
		"api": "https://huggingface.co/api/models/some-user/some-repo"
	},
	"headSha": "c379e821c9c95d613899e8c4343e4bfee2b0c600",
	"owner": {
		"id": "61d2000c3c2083e1c08af22d"
	}
}

repo.headSha는 저장소의 main 브랜치에서 최신 커밋의 sha입니다. event.scope가 "repo"로 시작하는 경우에만 전송되며, 토론이나 댓글과 같은 커뮤니티 이벤트나 Git 히스토리가 없는 버킷에는 전송되지 않습니다.

코드 변경 사항

코드 변경 시, 리포지토리 이벤트에는 최상위 속성 updatedRefs가 지정됩니다. 이는 업데이트된 참조(reference)들의 배열입니다. 예시 값은 다음과 같습니다:

"updatedRefs": [
  {
    "ref": "refs/heads/main",
    "oldSha": "ce9a4674fa833a68d5a73ec355f0ea95eedd60b7",
    "newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
  },
  {
    "ref": "refs/tags/test",
    "oldSha": null,
    "newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
  }
]

새로 생성된 참조는 oldSha가 null로 설정됩니다. 삭제된 참조는 newSha가 null로 설정됩니다.

특정 pull request, 새 태그, 또는 새 브랜치에 대한 새 커밋에 반응할 수 있습니다.

버킷

Buckets은 Git 저장소가 아닙니다. 커밋, 브랜치, 태그가 없습니다. 라이프사이클 이벤트(create, delete, move 및 가시성 설정 업데이트 등)는 다른 저장소 유형과 동일한 "repo" / "repo.config" 스코프를 사용합니다.

파일 변경은 "repo.content"를 사용하지만, 페이로드에는 updatedRefs 대신 updatedFiles 속성이 있습니다. 기존 파일을 덮어쓰는 경우 "add"로 보고됩니다. 파일 하나가 추가되고 다른 파일 하나가 삭제된 후의 페이로드 예시는 다음과 같습니다:

{
  "event": {
    "action": "update",
    "scope": "repo.content"
  },
  "repo": {
    "type": "bucket",
    "name": "some-user/some-bucket",
    "id": "6366c000a2abcdf2fd69a080",
    "private": false,
    "url": {
      "web": "https://huggingface.co/buckets/some-user/some-bucket",
      "api": "https://huggingface.co/api/buckets/some-user/some-bucket"
    },
    "owner": {
      "id": "61d2000c3c2083e1c08af22d"
    }
  },
  "updatedFiles": [
    {
      "path": "data/train.txt",
      "action": "add",
      "xetHash": "55faef2f2f80cd1a087c35b729f228960739441d38073cd5aa4320751e137166",
      "size": 20
    },
    {
      "path": "data/old.txt",
      "action": "delete"
    },
    ...
  ],
  "updatedFilesTruncated": true,
  "webhook": {
    "id": "6390e855e30d9209411de93b",
    "version": 3
  }
}

10,000개 항목을 초과하면 목록이 잘려 나가며 updatedFilesTruncated가 true로 설정됩니다. 이 경우 전체 내용을 확인하려면 버킷을 나열하세요.

Buckets에는 토론이나 Pull Request가 없으므로, 해당 이벤트에 대해 "discussion" 및 "discussion.comment" 이벤트를 절대 수신하지 않습니다.

클라이언트가 자체 서버로의 콜백을 통해 간접적으로 추적하는 대신 버킷의 파일 변경 사항을 직접 추적하려면, 버킷은 live follow stream도 제공합니다.

설정 변경

최상위 속성 event.scope가 "repo.config"인 경우, updatedConfig 속성이 지정됩니다. 이 속성은 업데이트된 config를 포함하는 객체입니다. 값의 예시는 다음과 같습니다:

"updatedConfig": {
  "private": false
}

업데이트된 config 키가 webhook에 의해 지원되지 않으면 객체가 비어 있습니다:

"updatedConfig": {}

현재 private만 지원됩니다. 여기에 더 많은 config 키가 존재하면 도움이 된다면 website@huggingface.co로 알려 주시기 바랍니다.

토론 및 Pull Requests

최상위 속성 discussion는 커뮤니티 이벤트(토론 및 Pull Request)에 지정됩니다. discussion.isPullRequest 속성은 해당 토론이 Pull Request이기도 한지를 나타내는 boolean 값입니다(Hub에서 PR은 토론의 특수한 유형입니다). 아래는 예시 값입니다:

"discussion": {
	"id": "639885d811ae2bad2b7ba461",
	"title": "Hello!",
	"url": {
		"web": "https://huggingface.co/some-user/some-repo/discussions/3",
		"api": "https://huggingface.co/api/models/some-user/some-repo/discussions/3"
	},
	"status": "open",
	"author": {
		"id": "61d2000c3c2083e1c08af22d"
	},
	"isPullRequest": true,
	"changes": {
		"base": "refs/heads/main"
	}
	"num": 3
}

댓글

최상위 속성 comment은 댓글이 생성될 때(토론 생성 포함) 또는 업데이트될 때 지정됩니다. 다음은 예시 값입니다:

"comment": {
	"id": "6398872887bfcfb93a306f18",
	"author": {
		"id": "61d2000c3c2083e1c08af22d"
	},
	"content": "This adds an env key",
	"hidden": false,
	"url": {
		"web": "https://huggingface.co/some-user/some-repo/discussions/4#6398872887bfcfb93a306f18"
	}
}

Webhook secret

Webhook 시크릿을 설정하면 Webhook 핸들러 URL로 전송되는 페이로드가 실제로 Hugging Face에서 온 것인지 확인할 수 있어 유용합니다.

Webhook에 시크릿을 설정하면 모든 요청에 X-Webhook-Secret HTTP 헤더로 함께 전송됩니다. ASCII 문자만 지원됩니다.

핸들러 URL에 시크릿을 직접 추가하는 것도 가능합니다. 예를 들어, 쿼리 파라미터로 설정하는 경우: https://example.com/webhook?secret=XXX.

Webhook 핸들러에서 요청의 HTTP 헤더에 액세스하는 것이 복잡한 경우 이 기능이 유용할 수 있습니다.

전달 및 재시도

Webhook 페이로드가 Hub에서 이벤트가 발생한 직후 비동기적으로 전달됩니다. 순서가 보장되지 않습니다: 여러 이벤트가 짧은 시간 간격으로 발생하면 순서대로 도착하지 않을 수 있습니다.

핸들러는 2xx 상태 코드로 전달을 확인해야 합니다. 다른 상태 코드는 연결 오류와 마찬가지로 전달 실패로 간주되며, 백오프를 적용하여 재시도됩니다. 처리가 느린 경우, 전달이 실패로 간주되지 않도록 즉시 2xx로 응답하고 작업을 비동기적으로 수행하세요.

각 전달에는 고유한 Webhook-Id HTTP 헤더가 있습니다. 실패한 전달의 재시도는 동일한 ID를 재사용하므로, 이를 멱등성 키로 취급하여 각 이벤트를 한 번만 처리할 수 있습니다.

Webhook으로의 전송이 계속 실패하면 Webhook이 자동으로 중단되고 소유자에게 이메일로 알림이 전송됩니다. 설정에서 문제를 해결하고 다시 활성화할 수 있습니다.

요청 제한

각 Webhook은 24시간당 1,000회 트리거로 제한됩니다. 사용량은 Webhook 설정 페이지의 “Activity” 탭에서 확인할 수 있습니다.

Webhook의 트리거 수를 늘려야 하는 경우, PRO, Team 또는 Enterprise로 업그레이드한 후 website@huggingface.co로 문의해 주세요.

Webhook 개발하기

HTTPS 엔드포인트/URL이 없는 경우, 웹훅 테스트를 위한 공개 도구를 사용할 수 있습니다. 이러한 도구는 수신된 모든 요청을 캡처하는 catch-all 역할을 하며 200 OK 상태 코드를 반환합니다. Beeceptor는 임시 HTTP 엔드포인트를 생성하고 수신된 페이로드를 검토하는 데 사용할 수 있는 도구 중 하나입니다. 또 다른 유사한 도구는 Webhook.site입니다.

또한, 개발 중에는 실제 Webhook 페이로드를 로컬 머신에서 실행 중인 코드로 라우팅할 수 있습니다. 이는 더 빠른 통합을 위해 테스트 및 디버깅을 수행하는 좋은 방법입니다. 이를 위해 로컬호스트 포트를 인터넷에 노출하면 됩니다. 이 경로를 사용하려면 ngrok 또는 localtunnel을 사용할 수 있습니다.

Webhook 디버깅

웹훅에서 최근 생성된 이벤트를 쉽게 찾을 수 있습니다. 웹훅의 activity 탭을 열면 최근 이벤트 목록을 볼 수 있습니다.

여기에서 생성된 이벤트의 HTTP 상태 코드와 페이로드를 검토할 수 있습니다. 또한, Replay 버튼을 클릭하여 이러한 이벤트를 다시 재생할 수 있습니다!

Note: Webhook의 대상 URL 또는 secret을 변경한 경우, 이벤트를 재생하면 payload가 업데이트된 URL로 전송됩니다.

참고: 재전송된 이벤트는 원래 전달과 동일한 Webhook-Id로 전송됩니다.

자주 묻는 질문

조직 계정과 사용자 계정 중 어디에 웹훅을 정의할 수 있나요?

아니요, 현재는 지원되지 않습니다.

HF(또는 모든 모델과 같은 전체 저장소 유형)의 모든 이벤트에 구독하는 방법은 무엇인가요?

현재 최종 사용자에게 노출되지 않지만, website@huggingface.co로 이메일을 보내주시면 해당 설정을 변경해 드릴 수 있습니다.