Webhooks

Em vez de fazer polling, você pode receber um webhook: ao informar um callbackUrl na criação de uma geração, a API faz um POST para essa URL assim que a task atinge estado terminal (completed/failed).

Entrega

• A API faz um POST para o callbackUrl quando a task chega a completed ou failed.
• Timeout de 10s por tentativa.
• Até 3 tentativas: imediata + retry após 2s + retry após 4s.
• O seu endpoint deve responder 2xx para confirmar o recebimento. Qualquer outro status (ou timeout) conta como falha e dispara nova tentativa.

Headers do disparo

Autenticação — X-Webhook-Token

Cada disparo inclui o header X-Webhook-Token com o webhookToken exibido uma única vez quando você cria o token no painel (/account/tokens). O integrador deve comparar esse header com o valor guardado e rejeitar a requisição se não bater — assim você garante que o POST veio mesmo da Avatrix.

Payloads

task.completed:

{
  "event": "task.completed",
  "taskId": "...",
  "status": "completed",
  "resultUrl": "https://.../resultado.png",
  "creditsUsed": 12,
  "timestamp": "2026-06-18T..."
}

task.failed:

{
  "event": "task.failed",
  "taskId": "...",
  "status": "failed",
  "error": { "code": "PROVIDER_ERROR", "message": "..." },
  "timestamp": "2026-06-18T..."
}

Trate o webhook como uma otimização do polling, não como garantia única: como falhas de entrega são possíveis, mantenha a possibilidade de consultar GET /api/v1/tasks/:id como fallback.