lowpoly는 2026. 10. 30.에 지원 종료됩니다. 요청 오류를 피하려면 해당 날짜 전에 모델을 전환하세요.

Webhooks

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

Webhooks를 만드는 이유

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

설정 및 구성

webhook을 활성화하려면 개발자 플랫폼에서 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 페이로드를 검증하고 저장한 후에는 항상 성공 응답을 반환하세요.

작업의 최종 이벤트가 일반적인 처리 시간의 약 두 배가 지나도 도착하지 않으면, GET 엔드포인트로 해당 작업을 조회하세요. 일반적인 처리 시간과 대기 시간에 대해서는 작업 생명 주기를 참조하세요.

로컬 테스트를 위한 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을 테스트하는 동안 이 프로세스를 계속 실행해 두세요. webhook 전달을 중지하려면 Ctrl+C를 입력하세요.
    경로는 /webhook이고 포트는 3000입니다. 이 값들은 나중에 webhook 전달을 수신하는 자체 코드를 설정할 때 유용하게 사용될 수 있습니다.

Webhook 생성:

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

응답 예시

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