Pular para o conteúdo
Entrar Começar
API e webhooksv1
openapi.yaml
Menu da APIVisão geral

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"
}

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 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).

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.

Esta página em Markdown · llms.txt