Projetos e fases

Referência do webhook: eventos, cabeçalhos, assinatura e novas tentativas

O contrato de cada entrega: eventos do catálogo, cabeçalhos x-aproova-*, como verificar a assinatura e quando o Aproova tenta de novo.

Para quem éProprietáriosAdministradores

Revisado em 14 de novembro de 2026

Antes de começar

Um webhook criado em Configurações > Integrações (proprietário do espaço, Fluxo ou superior) e o segredo de assinatura exibido no formulário.

Visão rápida da tarefa

Comece por estas etapas. Se a tarefa tiver outros passos, eles aparecem logo abaixo.

Etapa 1
Eventos do catálogo: review.created (revisão criada), review.version_uploaded (versão enviada), review.comment_created (comentário criado), review.verdict_submitted (decisão enviada por um participante), review.approved (revisão aprovada), review.rejected (revisão rejeitada), review.changes_requested (ajustes pedidos), review.approval_reopened (aprovação reaberta), review.unlocked (revisão desbloqueada). Aprovação reaberta e revisão desbloqueada só chegam aos webhooks que marcarem esses eventos; as assinaturas existentes continuam recebendo apenas os eventos que já tinham. O botão Testar envia o evento webhook.test.
Etapa 2
Cabeçalhos de cada entrega: x-aproova-event (tipo do evento), x-aproova-delivery (identificador da entrega), x-aproova-timestamp (segundos desde 1970, UTC) e x-aproova-signature. Também vão user-agent Aproova-Webhooks/1.0 e, quando há corpo, content-type application/json. Cabeçalhos personalizados não substituem esses nomes.
Etapa 3
Assinatura: x-aproova-signature = "sha256=" seguido do HMAC-SHA256 em hexadecimal, calculado com o segredo do webhook sobre o texto "${timestamp}.${body}", onde timestamp é o valor de x-aproova-timestamp e body é o corpo bruto recebido (texto vazio em GET, DELETE ou sem corpo). Calcule sobre os bytes recebidos, antes de converter o JSON, e compare em tempo constante.

4Corpo padrão (JSON): event, event_id, created_at, workspace_id, locale e, quando existirem, proof, version, folder, teams, comment, decision, actor e whatsapp. Campos vazios são omitidos. O texto de comentários internos nunca é enviado.
5Campos opcionais de decisão: verification_method (authenticated_user, email_otp ou declared) e actor_verified (true só para authenticated_user e email_otp). Aparecem apenas em eventos de decisão que trazem essa evidência; em um corpo personalizado, use {{data.verification_method}} e {{data.actor_verified}}.
6Resposta: qualquer status 2xx conta como entregue. O Aproova espera até 6 segundos por resposta.
7Novas tentativas: falha de rede, tempo esgotado e os status 408, 425, 429 e 5xx são tentados de novo; outros status 4xx não. São no máximo 4 tentativas: a 2ª cerca de 5 minutos depois da 1ª falha, a 3ª cerca de 30 minutos depois e a 4ª cerca de 120 minutos depois. Depois da 4ª, a entrega fica como falha definitiva no histórico.
8Cada nova tentativa repete o mesmo event_id e o mesmo x-aproova-delivery. Use esse valor para ignorar repetições no destino. Se o espaço deixar de ter um plano com webhooks, a entrega falha sem nova tentativa.

Seu serviço confere a assinatura, reconhece repetições pelo event_id e responde 2xx rapidamente.

Assinatura não confere: calcule sobre o corpo bruto, sem reformatar o JSON, e use o segredo atual (gerar um novo segredo invalida o anterior).
Ação duplicada no destino: uma resposta lenta ou um 5xx gera nova tentativa. Guarde o event_id já processado.
Evento novo não chega: marque aprovação reaberta ou revisão desbloqueada na lista de eventos do webhook.