← Voltar para Configurações

Webhook de notificações WhatsApp

Referência técnica do JSON enviado pelo ERP quando uma notificação de Ordem de Serviço é disparada por automação.

1. Como funciona

O envio automatizado usa a mesma arquitetura segura adotada em Agendamentos.

ENVIO SERVER-SIDE ATIVO

1. Usuário solicitaA partir de uma OS ou ação em lote.

2. ERP preparaO backend lê somente os dados da empresa autenticada.

3. Dispatcher enviapg_net usa a URL protegida no Vault e assina o JSON com HMAC.

4. ERP registraHTTP, tentativas, resposta e falhas ficam nos logs da empresa.

2. Segurança, Vault e idempotência

A URL do webhook e o segredo HMAC ficam no Vault. Depois de salvar, o endereço completo não é devolvido ao navegador.

Cada envio recebe uma chave de idempotência única. O mesmo par empresa + idempotency_key não é criado duas vezes.

O link público da OS é tokenizado e revogável. O payload nunca contém CPF como credencial de acesso.

3. Requisição HTTP

Método POST, corpo JSON e Content-Type application/json. O webhook precisa usar HTTPS.

Content-Type: application/json
X-ERP-Event: os.whatsapp
X-ERP-Idempotency-Key: <uuid>
X-ERP-Signature: sha256=<HMAC SHA-256 em hexadecimal>
X-ERP-Signature-Version: v1

HTTP 2xx é considerado sucesso. Timeout, erro de rede e resposta fora de 2xx seguem o máximo de tentativas e o intervalo configurados em Configurações → Envio WhatsApp.

4. Payload JSON

Exemplo totalmente fictício. Em um envio real, teste será false.

{
  "teste": false,
  "cliente_nome": "Cliente Exemplo",
  "cliente_telefone": "+5513999999999",
  "numero_os": 12345,
  "status_atual": "Em andamento",
  "aparelho": "Smartphone Modelo Exemplo",
  "cor_aparelho": "Preto",
  "data_entrada": "2026-09-05",
  "previsao": "2026-09-08",
  "defeito_relatado": "Descrição fictícia do defeito.",
  "link_acompanhamento_os": "https://os.exemplo.invalid/?t=11111111-1111-4111-8111-111111111111",
  "ultimas_atualizacoes": [
    {
      "data_hora": "05/09/2026 09:30",
      "texto": "Atualização fictícia mais recente."
    },
    {
      "data_hora": "05/09/2026 08:30",
      "texto": "Segunda atualização fictícia."
    },
    {
      "data_hora": "05/09/2026 07:30",
      "texto": "Terceira atualização fictícia."
    }
  ]
}

5. Campos enviados

Campo	Tipo	Descrição
teste	boolean	`false` no envio real e `true` no botão de teste.
cliente_nome	string	Nome salvo na OS.
cliente_telefone	string	Telefone normalizado para formato internacional, por exemplo `+5513...`.
numero_os	number	Número da Ordem de Serviço.
status_atual	string/null	Status atual da OS.
aparelho	string/null	Snapshot do modelo do aparelho.
cor_aparelho	string/null	Snapshot da cor do aparelho.
data_entrada	string/null	Data de entrada, preferencialmente em `YYYY-MM-DD`.
previsao	string/null	Previsão da OS.
defeito_relatado	string/null	Defeito relatado na OS.
link_acompanhamento_os	string/null	Novo. Link público tokenizado e revogável da OS. Fica `null` quando a consulta pública não está ativa.
ultimas_atualizacoes	array	Até as 3 atualizações mais recentes, com `data_hora` e `texto`.

6. Teste de envio

Em Configurações → Envio WhatsApp, salve primeiro o webhook e clique em Testar envio com dados fictícios.

O teste usa exclusivamente dados fictícios, inclusive cliente, telefone, número da OS e link tokenizado de exemplo. Nenhum cliente ou OS real é consultado para formar esse payload.

7. Logs, retry e diagnóstico

A própria aba de configuração mostra pendentes, processando, erros e descartados, além dos últimos envios da empresa.

PendenteAguardando envio.

ProcessandoRequisição entregue ao pg_net.

Erro / retryNova tentativa será feita após o backoff.

DescartadoLimite de tentativas atingido ou configuração inválida.

8. Exemplo rápido no n8n

No Webhook node, receba o POST e use os campos normalmente nas etapas seguintes.

{{ $json.cliente_nome }}
{{ $json.cliente_telefone }}
{{ $json.numero_os }}
{{ $json.status_atual }}
{{ $json.link_acompanhamento_os }}
{{ $json.ultimas_atualizacoes }}

Para produção, recomenda-se validar X-ERP-Signature antes de executar ações externas e tratar teste = true separadamente.