Por que o callback das suas tarefas hiapi não está sendo acionado e como corrigir

Por que o callback das suas tarefas hiapi não está sendo acionado

Você enviou uma tarefa para POST https://api.hiapi.ai/v1/tasks incluindo o objeto callback; a tarefa foi concluída (quando você faz GET /v1/tasks/{taskId} consegue ver status: "success"), mas o seu endpoint nunca recebeu a notificação de estado terminal. Nenhuma requisição chegou ao seu servidor. Nenhuma nova tentativa. Nada nos logs.

Os callbacks do hiapi são entregues como HTTPS POST de servidor para servidor, vindos de fora da sua rede. Se qualquer elo desse caminho falhar — a URL não for acessível pela internet pública, o TLS não puder ser negociado, o seu handler não retornar 2xx rápido o suficiente, ou a verificação de assinatura do seu lado rejeitar a requisição — então, do ponto de vista da sua aplicação, essa notificação é “silenciosa”. A boa notícia: quase sempre é um dos poucos erros de configuração abaixo, e cada um é fácil de verificar.

Causas comuns (ordenadas por probabilidade)

1. A URL de callback não é acessível pela internet pública. localhost, 127.0.0.1, um IP dentro da sua VPC, ou um túnel ngrok expirado — o hiapi não consegue acessá-los.
2. Problemas de HTTPS / TLS. Certificado autoassinado, certificado expirado, cadeia de certificados intermediários ausente, ou nome de host incompatível. O hiapi só faz POST para URLs que começam com https:// e valida a cadeia de certificados.
3. O seu handler não retorna 2xx dentro do tempo limite. Se você executa operações demoradas de forma síncrona dentro do handler de callback (gravação no banco de dados, download de imagens, envio de notificações), a requisição expira antes de você retornar 200. Do ponto de vista do hiapi, isso é uma falha.
4. Você nunca registrou a Webhook Sign Key, e o seu handler rejeita requisições não assinadas. Se a chave de assinatura não foi gerada em Settings, o corpo das requisições entregues pelo hiapi não virá com o cabeçalho de assinatura — qualquer middleware de verificação que você tenha escrito tratará essa requisição como inválida e a descartará.
5. O objeto callback foi omitido no envio. Ele é opcional. Se você não o incluiu no POST /v1/tasks, nada será acionado. Você precisa, em vez disso, fazer polling com GET /v1/tasks/{taskId}.
6. A tarefa ainda está em execução. O callback só é acionado no estado terminal (success ou fail). Enquanto status for queued, handling ou archiving, o callback ainda não será enviado.
7. O host da URL de callback está em uma lista de bloqueio / o firewall corporativo bloqueia o tráfego de saída para ele. Menos comum, mas vale a pena verificar se você está em um ambiente de rede perimetral restrito.

Como corrigir: checklist de 7 passos

1. Confirme que a tarefa realmente chegou ao estado terminal. curl -H "Authorization: Bearer $HIAPI_KEY" https://api.hiapi.ai/v1/tasks/tk-hiapi-.... Se status for queued ou handling, o callback ainda não foi acionado — aguarde, não depure ainda.
2. Confirme que você enviou o objeto callback. Reveja o corpo da requisição que você enviou para POST /v1/tasks. Se faltou callback, a resposta é essa — adicione-o e reenvie, ou mude para polling.
3. Teste a URL de callback a partir da internet pública. De qualquer máquina fora da sua rede (um celular com rede móvel, um shell na nuvem, uma ferramenta curl online), execute curl -i -X POST https://your.domain.example/hiapi/callback -d '{}' -H "Content-Type: application/json". Você precisa receber um HTTP 2xx do seu próprio servidor. Se receber conexão recusada, erro de DNS ou qualquer resposta que não seja 2xx, corrija isso primeiro.
4. Valide a cadeia de certificados TLS. curl -vI https://your.domain.example/hiapi/callback 2>&1 | grep -i 'ssl\|cert'. Procure por SSL certificate problem. Se vir esse erro, instale a cadeia completa de certificados (certificado folha + intermediários) ou use um certificado gerenciado (Let's Encrypt, CDN, ACM).
5. Retorne 200 imediatamente e processe de forma assíncrona. Dentro do seu handler: grave o payload da requisição em uma fila / tabela, retorne 200 OK e processe o trabalho em um worker em segundo plano. Não deixe a resposta ser bloqueada por chamadas downstream lentas.
6. Gere a Webhook Sign Key e unifique a sua forma de verificação. Vá para /en/dashboard/settings → Webhook Sign Key → Generate e salve a chave. Se o seu handler valida assinaturas, use a chave salva; se não valida, desative temporariamente a verificação, confirme que a entrega funciona e depois reative-a.
7. Verifique /en/dashboard/logs. Os logs de chamadas mostram a requisição e seu estado terminal. Comparar o request_id dos seus logs de chamadas com o que o seu servidor realmente recebeu (se recebeu) é a forma mais rápida de distinguir “o callback saiu do hiapi” de “o callback chegou ao meu servidor”.

Exemplo mínimo de validação

Use o conteúdo abaixo para confirmar de ponta a ponta a sua chave de API, o caminho de criação de tarefa e o endpoint de callback. Escolha um modelo de imagem rápido para o teste de fumaça; de acordo com a documentação pública, o ID do modelo inclui um sufixo de capacidade:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {"prompt": "a cute cat"},
    "callback": {"url": "https://your.domain.example/hiapi/callback"}
  }'

Você deve receber imediatamente uma resposta JSON contendo um taskId, no formato tk-hiapi-.... Depois, assim que a tarefa passar para success ou fail, observe os logs do seu servidor para ver se há um POST de entrada para /hiapi/callback. Se a própria etapa de criação de tarefa retornar 401 Unauthorized, o problema está na chave — consulte Por que o hiapi retorna 429 (e o que fazer) para entender como funciona o envelope de erros do hiapi (a mesma estrutura hiapi_error se aplica a todos os códigos de status).

Links relacionados

• API Keys — verifique se a sua chave é válida e tem o escopo de permissões correto
• Settings — gere ou faça rotação da sua Webhook Sign Key
• Call Logs — confirme que o hiapi enviou o callback e qual foi o status da resposta
• API Reference — especificação completa de POST /v1/tasks e GET /v1/tasks/{id}
• Limite de taxa 429 do hiapi — detalhes sobre o envelope de erros para problemas relacionados do tipo “recebi um status, mas nenhum callback”

FAQ

O hiapi tenta novamente callbacks que falharam? Um callback só é considerado entregue quando o seu endpoint retorna uma resposta 2xx. Se o seu handler retornar 5xx, expirar o tempo limite ou falhar no handshake TLS, considere o callback como não entregue. O padrão mais robusto é: para qualquer tarefa que você enviou com callback, sempre use o polling com GET /v1/tasks/{taskId} como rede de segurança. Assim, mesmo que ocorra uma falha no caminho do callback, o resultado não será perdido.

A URL de callback pode usar HTTP em vez de HTTPS? Não. Apenas URLs que começam com https:// são aceitas. Se você estiver testando localmente, use um túnel que encerre o TLS para você (Cloudflare Tunnel, ngrok, tailscale funnel) e aponte o callback para um endpoint HTTPS público.

Por que o meu handler recebeu o corpo da requisição, mas a verificação de assinatura falhou? Ou (a) você gerou a Webhook Sign Key depois de enviar a tarefa — a requisição foi assinada com a chave antiga (ou sem chave) — então gere novamente, salve e envie uma nova tarefa; ou (b) o seu código de verificação reconstrói a string canônica de forma diferente do hiapi. Registre os bytes exatos do corpo da requisição que o seu servidor recebeu e execute o HMAC novamente sobre esses bytes exatos, sem fazer nenhuma reserialização de JSON no meio.

O taskId mostra success, mas não recebi callback nem URL de resultado. Solicite novamente GET /v1/tasks/{taskId} e verifique o array output. As URLs em output[*].url têm prazo de validade (expireAt); baixe-as imediatamente. A entrega do callback e a validade da URL são dois problemas independentes — mesmo sem callback, o endpoint GET é a fonte da verdade.

Vi o callback em /en/dashboard/logs, mas o meu servidor nunca o registrou. Isso indica que o problema está na sua rede perimetral, não no hiapi. Causas comuns incluem: regras de CDN / WAF bloqueando POSTs sem um User-Agent reconhecível da sua equipe, listas de permissão de IP no firewall, ou o seu proxy reverso reescrevendo o caminho. Permita esse POST de entrada no firewall e execute novamente.

A URL de callback consome o limite de taxa da minha conta? Não. Os callbacks são entregas do hiapi para você e não têm relação com o seu orçamento de taxa de POST /v1/tasks.