Skip to main content

​
Ikhtisar

Alih-alih melakukan polling GET /jobs/{id} berulang kali, Anda dapat menyediakan URL webhook untuk menerima POST request saat job Anda selesai. Ini lebih efisien dan mengurangi panggilan API yang tidak perlu.

​
Menggunakan Webhooks

Tambahkan header X-Webhook-URL ke request generasi mana pun. Ketika job mencapai status terminal (completed, failed, atau cancelled), API akan mengirim POST request ke URL Anda dengan data job lengkap. 
// 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

​
Payload Webhook

Ketika job selesai, URL webhook Anda menerima POST request dengan data job: 
{
  "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://..."]
  }
}

​
Praktik Terbaik

Merespons dengan cepat - Kembalikan status code 2xx sesegera mungkin. Proses data webhook secara asinkron bila perlu.
Validasi payload - Verifikasi job_id sesuai dengan job yang Anda mulai sebelum memproses hasil.
  • Gunakan endpoint HTTPS untuk keamanan
  • Terapkan idempotensi untuk menangani pengiriman ganda
  • Log penerimaan webhook untuk debugging

​
Webhooks vs Polling

PendekatanKelebihanKekurangan
WebhooksNotifikasi real-time, panggilan API lebih sedikitMembutuhkan endpoint publik
PollingBekerja di mana saja, tidak perlu serverLebih banyak panggilan API, ada sedikit delay
Gunakan webhooks bila Anda memiliki server yang dapat menerima HTTP request. Gunakan polling untuk aplikasi sisi klien atau ketika Anda tidak dapat mengekspos endpoint publik.

​
Langkah Berikutnya

Job Lifecycle

Pelajari status job dan polling status

Contoh Kode

Lihat contoh lengkap dengan penanganan webhook