Receber Webhooks no N8N

Conceituacao

Webhooks permitem que a Ogmma API envie eventos em tempo real para o N8N. Em vez de fazer polling (consultar repetidamente), o N8N recebe uma notificacao instantanea quando algo acontece -- uma mensagem foi recebida, enviada, entregue ou lida.

Este guia mostra como configurar o N8N para receber e processar esses eventos.

Pre-requisito

Certifique-se de que voce ja configurou a autenticacao no N8N antes de continuar.

Passo 1: Criar o Webhook Node no N8N

1.1 Adicionar Webhook Node

No editor do N8N, adicione um node Webhook como trigger (inicio do workflow).

1.2 Configurar o Node

Campo	Valor
HTTP Method	`POST`
Path	`ogmma-events`
Response Mode	`Immediately`
Response Code	`200`

1.3 URLs Geradas

O N8N gera duas URLs automaticamente:

URL	Uso
Test URL	Funciona apenas enquanto "Listen for test event" esta ativo no editor
Production URL	Funciona quando o workflow esta ativo (publicado)

Formato das URLs:

Test:       https://SEU-N8N.app.n8n.cloud/webhook-test/ogmma-events
Production: https://SEU-N8N.app.n8n.cloud/webhook/ogmma-events

Importante

Use a Production URL para webhooks reais. A Test URL funciona apenas enquanto o painel "Listen for test event" esta aberto no editor. Ao fechar o editor, a Test URL para de responder.

Passo 2: Registrar o Webhook na Ogmma API

Agora voce precisa informar a Ogmma API para enviar eventos para a URL do N8N.

Metodo

POST https://oapi.ogmma.com.br/v1/webhooks

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/webhooks" \
  -H "Authorization: Bearer oapi_sk_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://SEU-N8N.app.n8n.cloud/webhook/ogmma-events",
    "events": [
      "message.received",
      "message.sent",
      "message.delivered",
      "message.read"
    ],
    "secret": "meu-secret-seguro-para-hmac"
  }'

Response

{
  "data": {
    "id": "64f8b2c3e1a2b3c4d5e6f7e0",
    "url": "https://SEU-N8N.app.n8n.cloud/webhook/ogmma-events",
    "events": ["message.received", "message.sent", "message.delivered", "message.read"],
    "secret": "meu-secret-seguro-para-hmac",
    "active": true,
    "createdAt": "2025-01-15T10:40:00.000Z"
  }
}

Dica

Guarde o secret -- voce vai precisar dele para validar a assinatura HMAC dos eventos recebidos.

Consulte a documentacao completa em Criar Webhook.

Passo 3: Validar Assinatura HMAC (Recomendado)

A Ogmma assina todos os payloads com HMAC-SHA256 usando o secret que voce definiu. Validar a assinatura garante que o evento realmente veio da Ogmma e nao foi adulterado.

Adicionar Code Node

Apos o Webhook node, adicione um Code node com o seguinte codigo JavaScript:

const crypto = require('crypto');

// Seu secret (o mesmo usado ao criar o webhook)
const secret = 'meu-secret-seguro-para-hmac';

// Assinatura enviada pela Ogmma no header
const signature = $input.first().json.headers['x-ogmma-signature'];

// Payload recebido
const payload = JSON.stringify($input.first().json.body);

// Calcular HMAC esperado
const expectedSignature = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

// Comparar de forma segura (timing-safe)
const isValid = signature && crypto.timingSafeEqual(
  Buffer.from(expectedSignature, 'hex'),
  Buffer.from(signature, 'hex')
);

if (!isValid) {
  throw new Error('Assinatura HMAC invalida - evento rejeitado');
}

// Retornar o payload validado
return $input.first().json.body;

Nota

A validacao HMAC e opcional mas altamente recomendada em producao. Ela protege contra requisicoes falsas enviadas para sua URL de webhook.

Passo 4: Rotear por Tipo de Evento

Use um Switch node para direcionar cada tipo de evento para um tratamento especifico.

Configuracao do Switch Node

Campo	Valor
Mode	`Rules`
Data Type	`String`
Value	`{{ $json.event }}`

Regras

Regra	Condicao	Saida
1	`event` equals `message.received`	Branch "Mensagem Recebida"
2	`event` equals `message.sent`	Branch "Mensagem Enviada"
3	`event` equals `conversation.created`	Branch "Nova Conversa"
Fallback	Todos os outros	Branch "Outros Eventos"

Workflow Completo

[Webhook] → [Code: validar HMAC] → [Switch: tipo de evento]
  → message.received    → [Processar mensagem recebida]
  → message.sent        → [Atualizar status no CRM]
  → conversation.created → [Criar lead no CRM]
  → Fallback            → [Logar evento]

Eventos Disponiveis

A Ogmma API suporta 12 tipos de evento que podem ser enviados via webhook:

Evento	Descricao	Documentacao
`message.received`	Mensagem recebida de um contato	Detalhes
`message.sent`	Mensagem enviada confirmada pelo WhatsApp	Detalhes
`message.delivered`	Mensagem entregue (duplo check)	Detalhes
`message.read`	Mensagem lida (checks azuis)	Detalhes
`conversation.created`	Nova conversa criada	Detalhes
`conversation.closed`	Conversa encerrada	Detalhes
`channel.connected`	Canal WhatsApp conectado	Detalhes
`channel.disconnected`	Canal perdeu a conexao	Detalhes
`contact.created`	Novo contato criado	Detalhes
`contact.updated`	Contato atualizado	Detalhes
`bulk.completed`	Envio em massa concluido	Detalhes
`bulk.failed`	Envio em massa falhou	Detalhes

Para mais detalhes sobre webhooks, consulte a Introducao a Webhooks.

Exemplo de Payload

Quando o evento message.received e disparado, o N8N recebe um payload como este:

{
  "event": "message.received",
  "timestamp": "2025-01-15T10:45:00.000Z",
  "data": {
    "messageId": "6650a1b2c3d4e5f6a7b8c9f0",
    "conversationId": "6650a1b2c3d4e5f6a7b8c9e0",
    "channelId": "64f8b2c3e1a2b3c4d5e6f7c1",
    "from": "5511999999999",
    "type": "text",
    "content": "Ola, gostaria de saber o horario de funcionamento",
    "timestamp": "2025-01-15T10:45:00.000Z"
  }
}

Acessando Campos no N8N

Expressao N8N	Valor
`{{ $json.event }}`	`message.received`
`{{ $json.data.from }}`	`5511999999999`
`{{ $json.data.content }}`	Texto da mensagem
`{{ $json.data.channelId }}`	ID do canal
`{{ $json.data.conversationId }}`	ID da conversa

Workflow Pronto

Baixe o workflow completo com Webhook + HMAC + Switch de eventos:

Baixar receive-webhook-events.json

Troubleshooting

Webhook nao recebe eventos

Workflow esta ativo? -- O workflow precisa estar publicado (toggle "Active" ligado) para a Production URL funcionar
URL correta? -- Verifique se voce registrou a Production URL (nao a Test URL) na Ogmma API
Eventos selecionados? -- Verifique se os eventos desejados foram incluidos ao criar o webhook
HTTPS? -- A URL do webhook deve usar HTTPS. URLs HTTP sao rejeitadas pela Ogmma API

Erros de HMAC

Secret correto? -- O secret no Code node deve ser identico ao usado na criacao do webhook
Payload modificado? -- Nao modifique o body antes de validar o HMAC

Desativacao automatica

Se o N8N retornar erros repetidos (5 falhas consecutivas), a Ogmma desativa o webhook automaticamente. Para reativar, use o endpoint Atualizar Webhook com active: true.

Proximo Passo

Auto-Resposta -- combine webhooks com envio para criar um chatbot completo
Workflows Avancados -- cenarios complexos com IA, e-commerce e CRM

Conceituacao​

Passo 1: Criar o Webhook Node no N8N​

1.1 Adicionar Webhook Node​

1.2 Configurar o Node​

1.3 URLs Geradas​

Passo 2: Registrar o Webhook na Ogmma API​

Metodo​

cURL​

Response​

Passo 3: Validar Assinatura HMAC (Recomendado)​

Adicionar Code Node​

Passo 4: Rotear por Tipo de Evento​

Configuracao do Switch Node​

Regras​

Workflow Completo​

Eventos Disponiveis​

Exemplo de Payload​

Acessando Campos no N8N​

Workflow Pronto​

Troubleshooting​

Webhook nao recebe eventos​

Erros de HMAC​

Desativacao automatica​

Proximo Passo​