Pular para o conteúdo principal

Visão geral

Em vez de fazer polling em GET /jobs/{id}, forneça à Krea uma URL de webhook. A Krea envia o job para essa URL quando ele termina.

Usando webhooks

Adicione o cabeçalho X-Webhook-URL a qualquer requisição de geração. Quando o job for concluído, falhar ou for cancelado, a Krea enviará uma requisição POST para essa URL.

Payload do webhook

O corpo da requisição tem o mesmo formato da resposta de GET /jobs/{id}:

Verificando assinaturas

A Krea assina todos os webhooks com Ed25519. Verifique a assinatura antes de confiar em um payload e rejeite requisições sem assinatura. A Krea assina o SHA-256 em hexadecimal minúsculo do timestamp, da URL, dos metadados e do corpo bruto da requisição, unidos por quebras de linha:
Para verificar uma requisição:
  1. Verifique se X-Krea-Webhook-Url corresponde exatamente à X-Webhook-URL que você enviou com o job.
  2. Verifique se o timestamp está a no máximo 5 minutos do horário atual do seu servidor.
  3. Aceite a requisição se a assinatura for válida com qualquer chave em https://api.krea.ai/.well-known/jwks.json. Armazene as chaves em cache por no máximo 24 horas. A Krea publica uma nova chave 24 horas antes de começar a assinar com ela.
Calcule o hash dos bytes brutos do corpo, não de um JSON serializado novamente. Por exemplo, use express.raw() no Express, await request.arrayBuffer() em frameworks baseados na Fetch API ou request.get_data() no Flask. Se o cabeçalho X-Krea-Webhook-Metadata estiver ausente, trate-o como uma string vazia.

Entrega e novas tentativas

Retorne um 2xx em até 15 segundos. Se a requisição expirar, não conseguir se conectar ou receber um 5xx, 408, 423, 425 ou 429, a Krea tenta novamente por cerca de 10 minutos, com um novo timestamp e uma nova assinatura a cada vez. A Krea não tenta novamente para nenhum outro 4xx. O mesmo job pode chegar mais de uma vez, então faça a deduplicação com base em job_id e status.

Webhooks vs. polling

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

Gere uma imagem com a API, do início ao fim