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.

Payload do webhook

Quando a tarefa termina, o seu URL de webhook recebe um pedido POST com os dados da tarefa:

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

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