# Webhooks

> Como o Precificador avisa os seus sistemas: cadastro do endpoint, formato, entregas, tentativas e boas práticas.

URL: https://precificador3d.com.br/docs/api/webhooks

Um webhook é um `POST` que o Precificador faz para uma URL sua quando algo muda. Assim a sua integração não precisa consultar a API o tempo todo.

## Cadastrar um endpoint

1. No app, abra **Configurações › Integrações › Webhooks** e clique em **Novo endpoint**.
2. Cole a URL (só `https`, porta 443) e escolha os eventos.
3. Confirme a senha. O **segredo** do endpoint (`whsec_…`) aparece uma vez: guarde junto da sua integração. Ele fica cifrado do nosso lado.
4. Clique em **Enviar teste** para ver o formato chegando.

Bancada: 1 endpoint. Oficina: até 3. Farm: até 10. Na v1, os endpoints só são cadastrados pela tela.

## O que chega

```http
POST /webhooks/precificador HTTP/1.1
Content-Type: application/json
User-Agent: Precificador3D-Webhooks/1
Precificador-Evento: cotacao.aprovada
Precificador-Evento-Id: 7b0c1d2e-3f4a-4b5c-8d6e-7f8a9b0c1d2e
Precificador-Entrega-Id: 2f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c
Precificador-Tentativa: 1
Precificador-Assinatura: t=1759510800,v1=5f2b…

{
  "id": "7b0c1d2e-3f4a-4b5c-8d6e-7f8a9b0c1d2e",
  "tipo": "cotacao.aprovada",
  "versao": "v1",
  "criado_em": "2026-10-03T14:00:00-03:00",
  "conta_id": "0b8e4c7a-5d2f-4a8e-9c1b-2f3a4b5c6d7e",
  "dados": { "objeto": "cotacao", "id": "9e0f1a2b-3c4d-4e5f-6a7b-8c9d0e1f2a3b", "codigo": "COT-0042" },
  "url": "https://api.precificador3d.com.br/v1/cotacoes/9e0f1a2b-3c4d-4e5f-6a7b-8c9d0e1f2a3b"
}
```

> **O aviso diz só o que mudou:** O corpo traz o id e poucos campos, sem dado pessoal, custo ou valor. Para ter o estado atual, **reconsulte a API** na `url` do evento com a sua chave.

## Entregas e tentativas

- Sucesso é qualquer `2xx` em até **5 segundos**. Redirecionamento conta como falha (não seguimos `3xx`).
- Sem sucesso, tentamos de novo até **8 vezes**, com espera crescente e aleatória (em torno de 1 a 2 dias no total).
- Depois de **20 falhas seguidas** ao longo de pelo menos 24 horas, o endpoint é desligado e o dono recebe um e-mail. Religar é manual, na tela.
- Responder `410 Gone` desliga o endpoint na hora.
- A ordem não é garantida e o mesmo evento pode chegar mais de uma vez.
- A tela mostra as últimas 100 entregas de cada endpoint (status, duração e tipo de erro) e permite reenviar.

## Boas práticas

- [Verifique a assinatura](https://precificador3d.com.br/docs/api/webhooks/assinatura) antes de usar o corpo.
- Responda `2xx` rápido e processe depois, numa fila.
- Guarde o `id` do evento e ignore repetidos.
- Reconsulte a API em vez de confiar no corpo.
- De tempos em tempos, reconcilie com `atualizado_desde` ([Paginação](https://precificador3d.com.br/docs/api/paginacao#reconciliar)).

## n8n, Zapier e Make

- **Receber eventos:** crie um gatilho "Webhook" (n8n) ou "Catch Hook" (Zapier, Make), copie a URL e cadastre no app escolhendo os eventos. Use "Enviar teste" para ver o formato.
- **Chamar a API:** nó "HTTP Request" com o cabeçalho `Authorization: Bearer <chave>` guardado nas credenciais da ferramenta, nunca no texto do fluxo.
- **Conferir a assinatura no n8n:** nó "Crypto" (HMAC, SHA256, hex) sobre o corpo cru (opção "Raw Body" no nó Webhook), comparado com o `v1=` do cabeçalho.