GET /jobs/{id}를 반복해서 폴링하는 대신, 작업이 완료될 때 POST 요청을 받을 웹훅 URL을 제공할 수 있습니다. 이는 더 효율적이며 불필요한 API 호출을 줄여줍니다.
웹훅 사용하기
어떤 생성 요청에든 X-Webhook-URL 헤더를 추가하세요. 작업이 종료 상태(completed, failed, cancelled)에 도달하면 API가 제공한 URL로 전체 작업 데이터를 담아 POST 요청을 보냅니다.
// npm install @krea-ai/sdk
import { Krea } from "@krea-ai/sdk";
const krea = new Krea({ apiKey: process.env.KREA_API_KEY });
const job = await krea.image(
"bfl/flux-1-dev",
{
prompt: "a serene mountain landscape at sunset",
width: 1024,
height: 576
},
{ webhookUrl: "https://your-server.com/webhook" }
);
console.log(`Job ID: ${job.job_id}`);
// Your webhook will receive the results when complete
웹훅 페이로드
작업이 완료되면 웹훅 URL은 다음과 같은 작업 데이터가 담긴 POST 요청을 받습니다:
{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"created_at": "2025-01-15T10:30:00.000Z",
"completed_at": "2025-01-15T10:30:05.000Z",
"result": {
"urls": ["https://..."]
}
}
모범 사례
빠르게 응답하세요 - 2xx 상태 코드를 신속하게 반환하세요. 필요하다면 웹훅 데이터는 비동기로 처리하세요.
페이로드를 검증하세요 - 결과를 처리하기 전에 job_id가 여러분이 시작한 작업과 일치하는지 확인하세요.
- 보안을 위해 HTTPS 엔드포인트를 사용하세요
- 중복 전달에 대비해 멱등성을 구현하세요
- 디버깅을 위해 웹훅 수신 로그를 남기세요
웹훅 대 폴링
| 방식 | 장점 | 단점 |
|---|
| 웹훅 | 실시간 알림, 적은 API 호출 | 공개 엔드포인트 필요 |
| 폴링 | 어디서나 동작, 서버 불필요 | API 호출 증가, 약간의 지연 |
다음 단계
Job Lifecycle
작업 상태와 상태 폴링에 대해 알아보기
Code Examples
웹훅 처리가 포함된 전체 예제 보기
