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

Webhooks

API 작업이 진행되거나 완료될 때 Meshy가 서버로 POST 요청을 보내도록 하여, 폴링을 할 필요가 없도록 하세요.

Webhooks를 사용하는 이유

Webhooks는 각 작업의 상태를 API로 폴링하는 것보다 작업량이 적고 비용도 적게 듭니다. Meshy는 업데이트가 발생할 때마다 바로 전송하므로 더 빨리 받을 수 있으며, Webhooks는 폴링보다 확장성이 좋습니다. 또한 보내는 요청 수가 줄어들어 속도 제한에 여유가 생깁니다.

Webhook 설정하기

Webhook을 추가하려면 다음 단계를 따르세요:

  1. 개발자 플랫폼에서 Webhooks 페이지를 열고 Create Webhook을 클릭합니다.
  2. Payload URL에 전달을 수신할 URL을 입력합니다. Meshy는 https://로만 전달합니다.
  3. 대화상자가 채워주는 Webhook Secret의 사본을 보관하세요. 모든 전달에 이 값이 포함되므로, 서버에서 요청이 Meshy로부터 온 것인지 확인할 수 있습니다. 이미 가지고 있는 Webhook의 경우, Secret 열의 눈 아이콘을 클릭하면 확인할 수 있습니다.
  4. Active를 선택하고 Confirm을 클릭합니다.

각 계정은 활성 Webhook을 5개까지, 전체로는 10개까지 가질 수 있습니다. 모든 활성 Webhook은 귀하의 모든 API 작업에 대한 상태 업데이트를 수신합니다.

컴퓨터의 서버로 Webhook을 테스트하려면 컴퓨터에서 테스트하기를 참고하세요.

전달 처리하기

전달을 수락하려면 200이나 202와 같이 400 미만의 상태로 응답하세요. Meshy는 응답을 약 25초까지 기다리므로, 먼저 전달을 저장한 다음 응답하세요. 모델 다운로드와 같은 느린 작업은 그 이후에 처리하세요.

400 이상의 상태이거나 응답이 없으면 전달 실패로 간주됩니다. Meshy는 시도 간격을 점점 늘려가며 재시도하며, IN_PROGRESS 업데이트는 최대 4회, 최종 상태는 최대 9회까지 재시도합니다. 연속으로 20개의 업데이트가 모든 시도에서 실패하면 Meshy가 해당 Webhook을 비활성화할 수 있습니다. 다시 활성화하려면 Webhooks 페이지에서 수정한 후 Active를 선택하세요.

다음과 같은 경우를 대비해 코드를 작성하세요:

  • 전달은 순서가 뒤바뀐 채 도착할 수 있습니다. IN_PROGRESS 전달이 최종 전달 이후에 도착할 수 있으므로, 이것이 최종 상태를 덮어쓰지 않도록 하세요.
  • 동일한 업데이트가 두 번 이상 도착할 수 있습니다. id와 status의 각 조합은 한 번만 처리하세요.
  • 귀하의 URL을 아는 누구나 요청을 보낼 수 있습니다. X-MESHY-API-WEBHOOK-SECRET-KEY를 보관해 둔 비밀 값과 비교하여, 일치하지 않는 요청은 거부하세요.

작업의 일반적인 소요 시간의 약 두 배가 지나도 최종 전달이 도착하지 않았다면, 해당 작업의 GET 엔드포인트에서 작업을 가져오세요. 일반적인 소요 시간과 대기 시간에 대해서는 작업 수명 주기를 참고하세요.

컴퓨터에서 테스트하기

Meshy는 공개된 https:// URL로만 전달하므로, 컴퓨터의 서버로 직접 전달할 수 없습니다. 컴퓨터에서 코드를 테스트하려면 webhook 프록시를 사용해 공개 URL을 컴퓨터로 전달하세요. 다음 단계에서는 smee.io를 사용하지만, 어떤 webhook 프록시 서비스든 동일한 방식으로 작동합니다.

  1. smee.io를 열고 Start a new channel을 클릭합니다. Webhook Proxy URL 아래의 URL을 복사합니다.

  2. smee 클라이언트가 아직 없다면 설치하세요:

    npm install --global smee-client

  3. 채널을 서버로 전달합니다. 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

    테스트하는 동안 계속 실행해 두세요. 전달을 중지하려면 Ctrl+C를 누르세요. 서버는 포트 3000의 /webhook 경로에서 전달을 수신하므로, 해당 위치에서 수신하도록 코드를 설정하세요.

  4. Webhooks 페이지에서 웹훅 프록시 URL을 Payload URL로 지정하여 Webhook을 생성합니다.

전달 페이로드

Meshy는 작업이 IN_PROGRESS일 때 전달을 한 번 보내고, 작업이 최종 상태에 도달하면 또 한 번 보냅니다. 작업은 IN_PROGRESS 전달 없이도 최종 상태에 도달할 수 있습니다.

각 전달은 다음 헤더와 함께 Payload URL로 보내는 POST 요청입니다:

헤더값
X-MESHY-API-WEBHOOK-SECRET-KEYWebhook의 시크릿
X-MESHY-API-WEBHOOK-USER-IDWebhook을 소유한 Meshy 사용자의 ID
Meshy-Webhook-Version본문의 형식인 v1
Content-Typeapplication/json
User-AgentMeshyAPIWebhook/1.0.0

JSON 본문은 작업 객체입니다. 이는 작업의 GET 엔드포인트가 반환하는 것과 동일한 객체이지만, progress는 예외입니다. 전달에서 progress는 다음 값 중 하나로 전송됩니다:

  • 작업이 IN_PROGRESS일 때 50
  • 작업이 성공했을 때 100
  • 작업이 실패했거나 취소되었을 때 0

각 작업 객체의 필드와 예시는 다음 섹션을 참고하세요: