Webhooks

Um destino pertence à empresa e exige webhook:gerenciar. O segredo é exibido no recibo de configuração e não aparece nas consultas seguintes.

Configurar

Crie com PUT /v1/webhook, If-None-Match: * e Idempotency-Key. Para alterar, rotacionar ou reativar, consulte GET /v1/webhook e envie seu ETag completo em If-Match.

{ "url": "https://integracao.example/eventos" }

O destino precisa ser HTTPS público na porta 443, sem credenciais ou fragmento. Cada alteração gera um segredo novo e invalida novas entregas da versão anterior. A configuração não testa a conexão.

DELETE /v1/webhook revoga o destino com If-Match e Idempotency-Key. Uma requisição que já estava em trânsito ainda pode chegar; novas entregas daquela versão deixam de ser autorizadas.

Validar a assinatura

O receptor recebe:

Cabeçalho	Valor
Cotejar-Event-Id	UUID estável para deduplicação.
Cotejar-Timestamp	Segundos Unix da tentativa.
Cotejar-Signature	v1= seguido do HMAC-SHA256 hexadecimal.

A entrada do HMAC é timestamp + "." + event_id + "." + bytes_exatos_do_corpo. Use o segredo completo, inclusive o prefixo ctj_whsec_. Confira a assinatura antes de interpretar o JSON, rejeite horários com diferença superior a cinco minutos e compare em tempo constante.

Depois da conferência, grave o ID do evento na mesma transação que aceita o processamento. Outra tentativa pode trazer novo timestamp e assinatura para o mesmo evento; não aplique o efeito novamente.

Eventos

Os tipos atuais são:

• catalogo.aplicado e catalogo.revisao_necessaria;
• analise.concluida e analise.falhou;
• divergencias.alteradas;
• vigilancia.degradada e vigilancia.restabelecida;
• webhook.teste.

Não há garantia de ordem de entrega. Somente uma resposta HTTP 2xx concluída confirma a tentativa. Redirecionamentos não são seguidos.

Histórico, teste e reenvio

Rota	Uso
GET /v1/webhook/eventos	Eventos mais recentes e estado das entregas.
GET /v1/webhook/eventos/{id}	Envelope lógico original e metadados sanitizados.
GET /v1/webhook/eventos/{id}/tentativas	Tentativas em ordem crescente.
POST /v1/webhook/testes	Agenda um evento de teste.
POST /v1/webhook/eventos/{id}/reenvios	Abre novo ciclo para evento encerrado.

Teste e reenvio exigem destino ativo, assinatura ativa, ETag atual e idempotência. O 202 confirma o aceite na fila, não a conexão. Os dois POSTs compartilham o teto de cinco pedidos por minuto e por empresa.

O reenvio aceita evento entregue, falhou ou cancelado com menos de 30 dias. Ele preserva ID e corpo, abre outro ciclo de até oito tentativas em 24 horas e autoriza explicitamente o destino atual, inclusive depois de uma rotação. O receptor continua deduplicando pelo ID.

Retenção

Eventos encerrados há mais de 30 dias ficam elegíveis para limpeza. Eventos pendentes ou em execução são preservados. Trinta dias não prometem exclusão instantânea se houver fila acumulada ou processamento indisponível.

Depois da retirada, a consulta devolve 404. Um recibo idempotente preservado ainda pode referenciar esse ID expirado; repetir o pedido não recria o evento nem outra entrega.