Esta documento mostra como configurar uma URL para receber webhooks, interpretar o payload recebido e responder corretamente para evitar falhas de entrega.

Quando usar

Use esta receita quando quiser que seu sistema seja notificado automaticamente sobre eventos da plataforma, como:

• Nova mensagem recebida
• Contato criado
• Contato atualizado
• Atendimento iniciado
• Atendimento encerrado
• Evento disparado pelo chatbot

Como funciona

Evento acontece na Digitalizei/WTS
        ↓
Webhook é disparado
        ↓
Seu sistema recebe uma requisição HTTP POST
        ↓
Seu sistema processa o payload
        ↓
Seu sistema responde 200 OK

Pré-requisitos

Antes de começar, você precisa ter:

• Uma URL pública para receber requisições HTTP
• Um endpoint configurado para aceitar método POST
• Certificado HTTPS válido
• Acesso à plataforma Digitalizei/WTS para configurar o webhook

Exemplo de URL:

https://api.seusistema.com/webhooks/digitalizei

Passo 1 — Criar o endpoint no seu sistema

Crie um endpoint público que receba requisições HTTP POST.

Exemplo em Node.js com Express:

import express from "express";

const app = express();

app.use(express.json());

app.post("/webhooks/digitalizei", async (req, res) => {
  const payload = req.body;

  console.log("Webhook recebido:", payload);

  return res.status(200).json({
    received: true
  });
});

app.listen(3000, () => {
  console.log("Servidor rodando na porta 3000");
});

Passo 2 — Configurar o webhook na plataforma

Na plataforma Digitalizei, acesse:

Configurações → Integrações → Webhooks

Crie uma nova assinatura de webhook.

Informe a URL do seu endpoint:

https://api.seusistema.com/webhooks/digitalizei

Selecione os eventos que deseja receber e salve a configuração.

Passo 3 — Entender o payload recebido

Os webhooks são enviados em formato JSON.

Estrutura padrão:

{
  "eventType": "CONTACT_UPDATED",
  "date": "2023-08-23T16:42:35.4359934Z",
  "content": {}
}

Campos principais

Passo 4 — Tratar o tipo do evento

Utilize o campo eventType para executar ações diferentes de acordo com o evento recebido.

Exemplo:

app.post("/webhooks/digitalizei", async (req, res) => {
  const { eventType, content } = req.body;

  switch (eventType) {
    case "CONTACT_CREATED":
      console.log("Novo contato criado:", content);
      break;

    case "CONTACT_UPDATED":
      console.log("Contato atualizado:", content);
      break;

    case "MESSAGE_RECEIVED":
      console.log("Nova mensagem recebida:", content);
      break;

    case "SESSION_ENDED":
      console.log("Atendimento encerrado:", content);
      break;

    default:
      console.log("Evento não tratado:", eventType);
  }

  return res.status(200).json({
    received: true
  });
});

Passo 5 — Responder corretamente

Após receber o webhook, seu sistema deve responder rapidamente com:

200 OK

Exemplo:

{
  "received": true
}

Essa resposta indica que o evento foi recebido com sucesso.

Exemplo completo de payload

{
  "eventType": "CONTACT_UPDATED",
  "date": "2023-08-23T16:42:35.4359934Z",
  "content": {
    "id": "ed2b52f8-cf13-449b-b3d5-ae27051f4663",
    "name": "João Raymond Legrasse",
    "phoneNumber": "+551000000000",
    "email": "[email protected]",
    "status": "ACTIVE"
  }
}

Exemplo com N8N

Você também pode receber webhooks utilizando o N8N.

Fluxo recomendado:

Webhook Trigger
        ↓
Switch por eventType
        ↓
Executar ação correspondente

Configuração básica

No N8N:

1. Adicione o node Webhook.
2. Configure o método como POST.
3. Copie a URL gerada.
4. Cole a URL na configuração de Webhooks da Digitalizei/WTS.
5. Adicione um node Switch para tratar o campo eventType.

Exemplo de roteamento

CONTACT_CREATED
        ↓
Criar lead no CRM externo

MESSAGE_RECEIVED
        ↓
Acionar IA ou automação

SESSION_ENDED
        ↓
Enviar pesquisa de satisfação

Boas práticas

Responda rapidamente

Evite processar tarefas longas antes de responder.

Recomendado:

Recebe webhook
        ↓
Salva evento ou envia para fila
        ↓
Responde 200 OK
        ↓
Processa depois

Evite:

Recebe webhook
        ↓
Executa várias integrações
        ↓
Só depois responde

Trate eventos duplicados

Em integrações críticas, considere que eventos podem ser reenviados.

Sempre que possível, utilize identificadores únicos do payload para evitar processamento duplicado.

Registre logs

Armazene informações como:

• eventType
• date
• ID do recurso recebido
• Status do processamento
• Erros ocorridos

Isso facilita auditoria e diagnóstico.

Valide a origem da requisição

Quando aplicável, valide:

• IP de origem
• HTTPS
• Headers
• Tokens internos
• Assinaturas

Implemente tratamento de erro

Caso ocorra falha no processamento interno, registre o erro e responda de acordo com sua estratégia.

Para evitar reprocessamentos desnecessários, muitos sistemas optam por responder 200 OK após salvar o evento em fila, mesmo que o processamento posterior ainda não tenha sido concluído.

Erros comuns

Minha URL não recebe eventos

Verifique:

• Se a URL está pública
• Se utiliza HTTPS
• Se aceita método POST
• Se não há bloqueio de firewall
• Se o webhook está ativo na plataforma

Recebo evento, mas minha automação falha

Verifique:

• Se o payload está sendo lido corretamente
• Se o campo eventType está sendo tratado
• Se os campos obrigatórios existem no content
• Se existem campos retornando null

O webhook demora para responder

Evite processamentos longos antes do retorno.

O ideal é responder rapidamente e processar em segundo plano.

Próximos passos

Depois de receber seu primeiro webhook, você pode avançar para:

• Configurar Webhook no Chatbot
• Criar automações no N8N
• Criar integrações no Make
• Consumir dados recebidos pela API
• Criar Recipes mais avançadas