Skip to main content

​
Visão geral

Em vez de fazer polling em GET /jobs/{id} repetidamente, você pode fornecer uma URL de webhook para receber uma requisição POST quando seu job for concluído. Isso é mais eficiente e reduz chamadas desnecessárias à API.

​
Usando webhooks

Adicione o cabeçalho X-Webhook-URL a qualquer requisição de geração. Quando o job atingir um estado terminal (completed, failed ou cancelled), a API enviará uma requisição POST para sua URL com os dados completos do job. 
// 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 do webhook

Quando o job for concluído, sua URL de webhook recebe uma requisição POST com os dados do 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://..."]
  }
}

​
Boas práticas

Responda rapidamente - Retorne um código de status 2xx prontamente. Processe os dados do webhook de forma assíncrona, se necessário.
Valide o payload - Verifique se o job_id corresponde a um job que você iniciou antes de processar os resultados.
  • Use endpoints HTTPS por segurança
  • Implemente idempotência em caso de entregas duplicadas
  • Registre em log os recebimentos de webhook para depuração

​
Webhooks vs polling

AbordagemVantagensDesvantagens
WebhooksNotificações em tempo real, menos chamadas de APIRequer um endpoint público
PollingFunciona em qualquer lugar, não requer servidorMais chamadas de API, pequeno atraso
Use webhooks quando você tiver um servidor capaz de receber requisições HTTP. Use polling para aplicações client-side ou quando não puder expor um endpoint público.

​
Próximos passos

Ciclo de vida do job

Aprenda sobre os estados do job e o polling de status

Exemplos de código

Veja exemplos completos com tratamento de webhook