← Voltar para Configurações

Webhook de notificações de Agendamentos

Referência técnica do JSON enviado pelo ERP quando o alerta de um compromisso é disparado por automação.

1. Como funciona

O envio automatizado usa a mesma arquitetura segura adotada no WhatsApp.

ENVIO SERVER-SIDE ATIVO

1. Alerta venceO servidor identifica o momento configurado para o compromisso.

2. ERP preparaO backend lê somente os dados do compromisso e da empresa correta.

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 alerta usa uma chave de idempotência própria para evitar processamento duplicado da mesma ocorrência.

O dispatcher processa somente a fila vinculada à empresa do compromisso; URL, HMAC e dados de outras empresas não são expostos ao frontend.

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: agendamento.alerta
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 → Agendamentos.

4. Payload JSON

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

{
  "teste": false,
  "evento": "agendamento.alerta",
  "versao": 1,
  "idempotency_key": "33333333-3333-4333-8333-333333333333",
  "agendamento_id": "44444444-4444-4444-8444-444444444444",
  "serie_id": "55555555-5555-4555-8555-555555555555",
  "descricao": "Reunião de Demonstração",
  "link": "https://meet.example.com/reuniao-demonstracao",
  "notas": "Compromisso fictício para documentação.",
  "dia_todo": false,
  "inicio_local": "2026-09-10T14:00:00",
  "fim_local": "2026-09-10T14:30:00",
  "timezone": "America/Sao_Paulo",
  "recorrencia": "nenhuma",
  "recorrencia_termina_tipo": "nenhuma",
  "numero_ocorrencia": 1,
  "alerta_minutos": 15,
  "alerta_em": "2026-09-10T16:45:00+00:00",
  "usuario": {
    "id": "11111111-1111-4111-8111-111111111111",
    "nome": "Marina Exemplo",
    "email": "marina.exemplo@example.com"
  },
  "origem_tipo": "manual",
  "criado_por": "22222222-2222-4222-8222-222222222222",
  "fora_expediente": false
}

5. Campos enviados

Campo	Tipo	Descrição
teste	boolean	`false` no alerta real e `true` no botão de teste.
evento	string	Sempre `agendamento.alerta`.
versao	number	Versão do contrato do payload.
idempotency_key	uuid	Identificador único do envio.
agendamento_id	uuid	Identificador da ocorrência do compromisso.
serie_id	uuid	Identificador da série do compromisso.
descricao	string	Descrição do compromisso.
link	string/null	Link de reunião ou acompanhamento; omitido quando vazio.
notas	string/null	Notas adicionais; omitidas quando vazias.
dia_todo	boolean	Indica compromisso sem horário específico.
inicio_local / fim_local	datetime	Data e hora local quando `dia_todo=false`.
inicio_data / fim_data	date	Datas usadas quando o compromisso é de dia todo.
timezone	string	Fuso horário aplicado à ocorrência.
recorrencia	string	`nenhuma`, `diaria`, `semanal`, `quinzenal`, `mensal` ou `anual`.
recorrencia_termina_*	string/date/number	Regra de encerramento da recorrência, quando aplicável.
numero_ocorrencia	number	Posição da ocorrência dentro da série.
alerta_minutos	number	Antecedência configurada para o alerta.
alerta_em	timestamptz	Instante absoluto em que o alerta é processado.
usuario	object	Responsável pelo compromisso, com `id`, `nome` e `email`.
origem_tipo	string	`manual` ou `tarefa`.
origem_id	uuid/null	Identificador da entidade de origem quando existir.
criado_por	uuid	Usuário que criou o compromisso.
fora_expediente	boolean	Indica ocorrência confirmada fora do expediente configurado.

6. Teste de envio

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

O teste usa exclusivamente dados fictícios, inclusive descrição, usuário, e-mail e UUIDs. Nenhum compromisso ou usuário 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.descricao }}
{{ $json.usuario.nome }}
{{ $json.inicio_local }}
{{ $json.alerta_minutos }}
{{ $json.link }}
{{ $json.recorrencia }}

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