웹훅 | Developer API

이미지 또는 비디오 생성 프로세스가 완료될 때 비동기식 실시간 HTTP 알림을 받으세요.

웹훅을 사용하면 생성 프로세스가 완료될 때 비동기 알림을 받을 수 있습니다. 업데이트를 확인하기 위해 /api/v1/status/{id} 엔드포인트를 수동으로 폴링하는 대신, 작업이 완료되는 즉시 저희 시스템이 최종 페이로드를 귀하의 서버로 직접 푸시합니다.

웹훅 사용 방법

저희 API와 함께 웹훅을 사용하려면, /run 요청에 webhook_url 매개변수를 추가하기만 하면 됩니다:

POSThttps://fititon.app/api/v1/run?webhook_url=https://your-server.com/webhook

생성 프로세스가 완료되면(성공적으로 완료되거나 런타임 오류가 발생한 경우), 저희 디스패처는 지정된 웹훅 URL로 전체 상태 페이로드를 포함하는 POST 요청을 보냅니다.

보안 요구 사항 보안 목적(SSRF 보호)을 위해 webhook_url은 HTTPS(https://)를 사용해야 합니다. 내부 또는 사설 IP 주소(예: localhost, 127.0.0.1, 192.168.x.x)는 엄격히 차단됩니다. 로컬에서 개발 중인 경우 Ngrok 또는 Cloudflare Tunnels와 같은 보안 터널링 서비스를 사용하십시오.

예시: `/run` 엔드포인트와 함께 웹훅 사용

fetch("https://fititon.app/api/v1/run?webhook_url=https://your-server.com/webhook", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
      // ... other inputs
    }
  }),
});

웹훅 페이로드

귀하의 웹훅 URL로 전달되는 페이로드는 /v1/status/{id} 엔드포인트에서 반환되는 페이로드와 동일합니다. 여기에는 작업의 최종 상태가 포함됩니다.

성공 페이로드

프로세스가 성공적으로 완료되면, 귀하의 웹훅 URL은 status가 "success"로 설정되고 output 배열에 결과가 포함된 POST 요청을 받게 됩니다:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "success",
  "output": [
    "https://cdn.fititon.app/users/123/results/output_0.png"
  ],
  "error": null,
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:31:15.000Z"
}

오류 페이로드

런타임 오류(예: 인식할 수 없는 의류, 엄격한 검열 필터)로 인해 프로세스가 실패하면, 귀하의 웹훅 URL은 정확한 오류 문자열을 받게 됩니다.

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "failed",
  "output": null,
  "error": {
    "name": "InputValidationError",
    "message": "The provided garment image could not be processed due to poor lighting."
  },
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:30:12.000Z"
}

웹훅 보안

수신하는 웹훅이 실제로 Fit It On에서 시작되었고 악의적인 제3자에 의해 위조되지 않았음을 확인하려면, 검증 메커니즘을 구현해야 합니다.

웹훅을 보호하는 가장 간단한 방법은 /v1/run 요청에 제공하는 webhook_url에 비밀 토큰을 추가하는 것입니다.

예시: 비밀 토큰 사용

생성 프로세스를 시작할 때, URL 쿼리 매개변수에 무작위성이 높은 문자열을 추가하십시오:

// Make sure to URL-encode the webhook URL if it contains query parameters!
const myWebhookUrl = encodeURIComponent("https://your-server.com/webhook?token=a8f9c2d1e5b47...");

fetch(`https://fititon.app/api/v1/run?webhook_url=${myWebhookUrl}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  // ...
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
    }
  }),
});

귀하의 서버가 웹훅 POST 요청을 받으면, JSON 페이로드를 처리하기 전에 token 쿼리 매개변수가 귀하의 비밀 문자열과 일치하는지 간단히 확인하십시오.

보장된 전송 및 재시도

저희 시스템은 귀하의 서버가 일시적인 다운타임을 겪더라도 웹훅 전송을 놓치지 않도록 엔터프라이즈급 재시도 메커니즘을 구현합니다.

타임아웃: 저희 디스패처는 엄격한 15초 타임아웃을 적용합니다. 귀하의 서버는 15초 이내에 2xx HTTP 상태 코드로 웹훅을 승인해야 합니다. 무거운 처리(예: 이미지 다운로드)를 수행해야 하는 경우, 웹훅에 먼저 응답하고 데이터를 비동기적으로 처리해야 합니다.
실패: 귀하의 서버가 2xx가 아닌 상태 코드(예: 500 Internal Server Error)를 반환하거나 15초 이내에 응답하지 못하면, 저희는 전송이 실패한 것으로 간주합니다.
지수 백오프: 시스템은 지수 백오프(예: 5분, 15분, 45분 등 후에 재시도)를 사용하여 최대 5회 재시도를 시도합니다.

현재 귀하의 서버에 도달하는 재시도 횟수를 알아야 하는 경우, 모든 웹훅 요청에 포함된 x-fititon-retry-count 헤더를 확인할 수 있습니다.

모범 사례

멱등성 구현: 네트워크 조건 및 저희의 재시도 메커니즘으로 인해, 귀하의 서버가 동일한 웹훅을 두 번 이상 수신할 수 있습니다. id 필드를 사용하여 이벤트를 이미 처리했는지 확인해야 합니다.
빠르게 응답: 이미지 다운로드 또는 데이터베이스 업데이트 전에 항상 즉시 200 OK 상태를 반환하십시오.
항상 웹훅 검증: 웹훅이 저희 서비스에서 오는지 확인하고 악의적인 행위자가 페이로드를 위조하는 것을 방지하기 위해 (위에 언급된 비밀 URL 토큰과 같은) 검증 메커니즘을 구현하는 것을 고려하십시오.

웹훅