Webhooks

Webhooks를 사용하면 API 작업이 완료되거나 상태가 변경될 때 Meshy로부터 실시간 업데이트를 받을 수 있습니다. 설정이 완료되면 Meshy는 지정한 URL로 json 형식의 이벤트 페이로드를 POST 방식으로 전송합니다.

Webhooks를 생성하는 이유

webhook을 사용하면 특히 API 작업 상태를 자동으로 확인하는 것과 관련하여 여러 이점이 있습니다. Webhooks는 API를 지속적으로 폴링하여 작업 상태 업데이트를 받는 것보다 노력과 비용이 적게 듭니다. 또한 Webhooks는 거의 실시간에 가까운 업데이트를 제공하며 결과적으로 API 폴링보다 더 잘 확장됩니다. 이를 통해 특히 지속적으로 폴링하는 경우 요청 한도(rate limit)를 더 잘 관리할 수 있습니다.

설정 및 구성

webhook을 활성화하려면 Developer Platform에서 Webhooks 페이지를 열고 "Create Webhook" 버튼을 클릭하세요. webhook을 받고자 하는 https URL을 입력하고 webhook을 활성화하여 Meshy로부터 작업 업데이트를 자동으로 받을 수 있습니다. Meshy 계정당 최대 5개의 활성 webhook을 가질 수 있습니다. webhook이 활성화되면 모든 API 작업 상태 업데이트가 자동으로 페이로드 URL로 전송됩니다. 보안상의 이유로 현재는 https URL로만 webhook을 전송할 수 있습니다. 로컬 테스트를 구성하려면 다음 섹션을 참조하세요.

Webhook 전달 요구 사항

webhook이 정상적으로 작동하고 계속해서 이벤트를 수신하려면:

  • 서버는 400 미만의 HTTP 상태 코드로 응답해야 합니다 (예: 200 OK, 202 Accepted).
  • 상태 코드가 >= 400인 응답은 전달 실패로 간주됩니다.
  • 연속된 여러 번의 실패는 다음과 같은 결과를 초래할 수 있습니다:
    • progress 업데이트가 지연되거나 순서가 뒤바뀔 수 있음
    • 반복된 시도 후 webhook이 자동으로 비활성화될 수 있음 (자동 비활성화 정책 참조)

팁: 추가 처리가 비동기적으로 이루어지더라도, webhook 페이로드를 검증하고 저장한 후에는 항상 성공 응답을 반환하세요.

로컬 테스트를 위한 Webhooks 전달

일반적으로 http 주소로 되어 있는 webhook 코드를 로컬에서 테스트하고 싶다면, 웹훅 프록시 URL을 사용하여 컴퓨터나 코드스페이스로 webhook을 전달할 수 있습니다. 아래는 smee.io를 사용한 권장 단계이지만, 웹훅 프록시 URL을 생성할 수 있는 어떤 서비스든 사용하셔도 됩니다.

웹훅 프록시 URL 받기:

  1. 브라우저에서 https://smee.io/ 로 이동합니다
  2. "Start a new channel"을 클릭합니다
  3. "Webhook Proxy URL" 아래의 전체 URL을 복사합니다. 이 URL은 다음 설정 단계에서 사용됩니다.

Webhooks 전달하기:

  1. smee-client가 아직 설치되어 있지 않다면, 터미널에서 다음 명령어를 실행하세요.
npm install --global smee-client
  1. smee.io로부터 전달된 webhook을 받으려면 터미널에서 다음 명령어를 실행하세요. WEBHOOK_PROXY_URL을 앞서 받은 웹훅 프록시 URL로 교체하세요.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

WEBHOOK_PROXY_URL이 웹훅 프록시 URL인 다음과 같은 출력이 표시됩니다:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. webhook을 테스트하는 동안 이 상태를 유지하세요. Webhooks 전달을 중지하려면 Ctrl+C를 입력하세요.
    경로는 /webhook이고 포트는 3000입니다. 이 값들은 나중에 webhook 전달을 받기 위한 코드를 직접 설정할 때 유용하게 사용될 수 있습니다.

Webhook 생성하기:

이제 웹훅 프록시 URL을 사용하여 Webhooks 페이지에서 새 webhook을 생성할 수 있습니다.

샘플 응답

작업 상태가 변경되면 Meshy는 구성된 URL로 webhook 페이로드를 POST 방식으로 전송합니다. 페이로드에는 JSON 형식의 작업 객체가 포함됩니다. 모든 작업 객체 속성과 예제 페이로드에 대한 전체 설명은 다음을 참조하세요: