Webhooks

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

Webhooks를 생성하는 이유

Webhooks를 사용하면 특히 API 작업 상태를 자동으로 확인하는 데 여러 가지 이점이 있습니다. Webhooks는 작업 상태 업데이트를 받기 위해 API를 지속적으로 폴링하는 것보다 더 적은 노력과 비용이 듭니다. 또한 Webhooks는 거의 실시간 업데이트를 가능하게 하며, API 폴링보다 더 나은 확장성을 제공합니다. 이는 특히 지속적으로 폴링하는 경우 속도 제한을 더 잘 관리할 수 있게 해줍니다.

설정 및 구성

Webhooks를 활성화하려면 Meshy 웹 애플리케이션에 로그인한 후 API 설정 페이지로 이동하세요. API 키 아래의 "Webhooks" 섹션을 찾아 "Webhook 생성" 버튼을 클릭하세요. Webhooks를 받을 원하는 https URL을 제공하고, Meshy로부터 작업 업데이트를 자동으로 받을 수 있도록 Webhook을 활성화하세요. Meshy 계정당 최대 5개의 활성 Webhooks를 가질 수 있습니다. Webhook이 활성화되면 모든 API 작업 상태 업데이트가 자동으로 페이로드 URL로 전송됩니다. 보안상의 이유로 현재는 https URL로만 Webhooks 전송을 허용합니다. 로컬 테스트를 구성하려면 다음 섹션을 참조하세요.

Webhook 전송 요구 사항

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

  • 서버는 400 미만의 HTTP 상태 코드로 응답해야 합니다 (예: 200 OK, 202 Accepted).
  • 상태 코드가 >= 400인 응답은 실패한 전송으로 처리됩니다.
  • 연속적인 실패는 다음을 초래할 수 있습니다:
    • progress 업데이트가 지연되거나 순서가 뒤바뀔 수 있음
    • 반복된 시도 후 자동으로 Webhook이 비활성화됨 (자동 비활성화 정책 참조)

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

로컬 테스트를 위한 Webhooks 전달

Webhook 코드를 로컬에서 테스트하려면, 일반적으로 http 주소에 있는 경우, Webhook 프록시 URL을 사용하여 Webhooks를 컴퓨터나 코드스페이스로 전달할 수 있습니다. 아래는 smee.io를 사용하는 권장 단계이지만, Webhook 프록시 URL을 생성하기 위해 원하는 서비스를 사용할 수 있습니다.

Webhook 프록시 URL 얻기:

  1. 브라우저에서 https://smee.io/로 이동하세요.
  2. "새 채널 시작"을 클릭하세요.
  3. "Webhook 프록시 URL" 아래의 전체 URL을 복사하세요. 이 URL은 다음 설정 단계에서 사용됩니다.

Webhooks 전달:

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

다음과 같은 출력이 표시되어야 하며, WEBHOOK_PROXY_URL은 Webhook 프록시 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 생성:

이제 Webhook 프록시 URL을 사용하여 Meshy API 설정 페이지에서 새 Webhook을 생성할 수 있습니다.

샘플 응답

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