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.

Payload do webhook

Quando o job for concluído, sua URL de webhook recebe uma requisição POST com os dados do job:

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

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