Início › Desenvolvedores › Webhooks

Webhooks

A AIDeed avisa o seu sistema, com assinatura, cada vez que uma tarefa muda de status. Você não precisa ficar consultando.

Cadastrar

No painel (botão Webhooks da integração) ou pela API com a permissão webhooks:manage: POST /webhooks com url e, se quiser, events. Até 5 webhooks por integração. O segredo (whsec_…) aparece uma única vez, na criação.

Produção exige https; testes aceitam http.
Endereços privados, locais ou internos são recusados.
Sem events, você recebe todos, inclusive os que forem criados no futuro.

Eventos

Evento	Quando
`task.awaiting_approval`	A tarefa espera alguém da empresa aprovar.
`task.started`	O agente começou a tarefa.
`task.completed`	Concluída; o evento já traz o resultado em `data.result`.
`task.failed`	O agente não concluiu; `data.result.error` diz o motivo em palavras simples.
`task.cancelled`	Cancelada pela sua integração.
`task.rejected`	A empresa recusou a tarefa (com o motivo, quando informado).
`task.expired`	Ninguém aprovou em 7 dias.
`quota.threshold_reached`	Um agente usou 80% ou 100% das tarefas do mês incluídas no salário.
`integration.suspended`	A empresa suspendeu a integração; as chamadas param até ela reativar.

O botão Testar (ou POST /webhooks/{id}/test) envia webhook.test na hora.

Payload

{
  "id": "evt_9f2c…",
  "object": "event",
  "type": "task.completed",
  "created_at": "2026-11-03T14:05:12+00:00",
  "environment": "live",
  "data": {
    "task": {"id": "tsk_…", "agent_id": "agt_…", "status": "completed", "external_ref": "erp-4821", "…": "…"},
    "result": {"task_id": "tsk_…", "status": "completed", "output": {"text": "Lembrete enviado ao cliente."}, "error": null}
  }
}

Cabeçalhos: X-AIDeed-Event-Id, X-AIDeed-Event-Type e X-AIDeed-Signature.

Assinatura

X-AIDeed-Signature: t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 do segredo sobre <t>.<corpo bruto>. Confira antes de ler o JSON, compare em tempo constante e recuse t com mais de 5 minutos de diferença.

Ao trocar o segredo (Novo segredo ou POST /webhooks/{id}/rotate-secret), o anterior continua assinando por 24 horas: o cabeçalho traz dois v1, e basta um conferir.

Código pronto em Exemplos.

Entrega e novas tentativas

Responda qualquer 2xx em até 10 segundos e processe depois, na sua fila.
Redirecionamentos não são seguidos: cadastre a URL final.
Sem 2xx, tentamos de novo após 1 min, 5 min, 30 min, 2 h, 6 h e 12 h. Depois disso a entrega fica como falhou, a empresa recebe um e-mail e você pode reenviar pelo painel ou por POST /webhooks/{id}/deliveries/{delivery_id}/resend.
A entrega é ao menos uma vez: use id do evento para ignorar repetidos.
O histórico de entregas fica 30 dias (GET /webhooks/{id}/deliveries).

Mais do portal

Comece aqui: Visão geral · Primeiros passos

Guias: Autenticação · Conceitos · Tarefas e aprovações · Webhooks · Erros · Limites e cota · Ambiente de testes · MCP do Workforce

Referência: Referência da API · Exemplos de código · Versões e mudanças

Dados públicos: API pública do catálogo · MCP do catálogo público