Skip to main content

​
Visão geral

Em vez de consultar GET /jobs/{id} repetidamente, pode fornecer um URL de webhook para receber um pedido POST quando a sua tarefa terminar. Isto é mais eficiente e reduz chamadas de API desnecessárias.

​
Utilizar webhooks

Adicione o cabeçalho X-Webhook-URL a qualquer pedido de geração. Quando a tarefa chegar a um estado terminal (completed, failed ou cancelled), a API enviará um pedido POST para o seu URL com os dados completos da tarefa. 
// 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 a tarefa termina, o seu URL de webhook recebe um pedido POST com os dados da tarefa: 
{
  "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 — devolva um código de estado 2xx sem demora. Processe os dados do webhook de forma assíncrona, se necessário.
Valide o payload — verifique se o job_id corresponde a uma tarefa que iniciou antes de processar os resultados.
  • Utilize endpoints HTTPS por segurança
  • Implemente idempotência para o caso de entregas duplicadas
  • Registe a receção de webhooks para depuração

​
Webhooks vs polling

AbordagemPrósContras
WebhooksNotificações em tempo real, menos chamadas de APIRequer um endpoint público
PollingFunciona em qualquer lado, não é necessário servidorMais chamadas de API, ligeiro atraso
Use webhooks quando tiver um servidor que possa receber pedidos HTTP. Use polling em aplicações do lado do cliente ou quando não puder expor um endpoint público.

​
Próximos passos

Ciclo de vida das tarefas

Saiba mais sobre os estados das tarefas e o polling de estado

Exemplos de código

Veja exemplos completos com tratamento de webhooks