Webhooks

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

Webhooks를 만드는 이유

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

설정 및 구성

webhooks를 활성화하려면 Meshy 웹 애플리케이션에 로그인한 상태에서 API 설정 페이지로 이동하세요. API Keys 아래의 "Webhooks" 섹션을 찾아 "Create Webhook" 버튼을 클릭하세요. Meshy로부터 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 전달

일반적으로 http 주소에서 실행되는 webhook 코드를 로컬에서 테스트하려면 웹훅 프록시 URL을 사용하여 webhooks를 컴퓨터나 codespace로 전달할 수 있습니다. 아래는 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에서 전달된 webhooks를 수신하려면 터미널에서 다음 명령을 실행하세요. 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을 사용하여 Meshy API 설정 페이지에서 새 webhook을 만들 수 있습니다.

샘플 응답

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