Recebendo Mensagens

A aba Recebimento é onde você configura como o Datacrazy recebe mensagens do serviço externo via webhook.

URL do Webhook

Após criar a instância, o Datacrazy gera automaticamente uma URL do Webhook exibida na aba Recebimento. Configure essa URL no painel do serviço externo como destino dos webhooks.

⚠️ Importante: O endpoint sempre retorna { "success": true } com HTTP 200, independentemente do resultado do processamento interno. Isso evita que o serviço externo faça retentativas desnecessárias.

Habilitando o recebimento

Ative o toggle Habilitar recebimento de mensagens para começar a processar webhooks recebidos.

Mapeamento de Campos

A seção Mapeamento de Campos define como extrair os dados relevantes do payload JSON enviado pelo serviço externo. Preencha cada campo com o caminho usando dot notation (notação de ponto).

Campos obrigatórios

Campo	Descrição	Exemplo de caminho
Caminho do ID do Contato	ID único do remetente	`message.from.id`
Caminho do Corpo da Mensagem	Conteúdo da mensagem	`message.text`
Caminho do ID da Mensagem	ID único da mensagem (para idempotência)	`update_id`

Campos opcionais

Campo	Descrição	Exemplo de caminho
Caminho do Nome do Contato	Nome do remetente	`message.from.first_name`
Caminho do Timestamp	Data/hora da mensagem	`message.date`
Caminho da URL do Anexo	URL do anexo recebido	`message.document.file_path`
Caminho do Tipo do Anexo	Tipo MIME do anexo	`message.document.mime_type`
Caminho do ID Externo da Mensagem	ID alternativo da mensagem	`message.message_id`

Exemplo

Considerando que o serviço externo envia um payload como:

{
  "update_id": 123456,
  "message": {
    "message_id": 789,
    "from": {
      "id": 111222333,
      "first_name": "João"
    },
    "text": "Olá!",
    "date": 1700000000
  }
}

Preencha os campos:

Caminho do ID do Contato: message.from.id
Caminho do Nome do Contato: message.from.first_name
Caminho do Corpo da Mensagem: message.text
Caminho do ID da Mensagem: update_id
Caminho do Timestamp: message.date

Validação do Webhook

A seção Validação do Webhook permite verificar se os webhooks recebidos são legítimos. O Datacrazy verifica o header especificado usando o algoritmo configurado.

Campo	Descrição
Header de Assinatura	Nome do header que contém a assinatura (case-insensitive)
Algoritmo	Algoritmo de validação (selecione no dropdown)
Segredo de Validação	Chave secreta para validação

Algoritmos disponíveis

Algoritmo	Descrição
`static`	Comparação direta do valor do header com o segredo configurado
`sha256`	Hash SHA-256 do corpo da requisição
`sha1`	Hash SHA-1 do corpo da requisição
`hmac-sha256`	HMAC-SHA256 do corpo com o segredo (suporta prefixo `sha256=`)

⚠️ Nota: Se o Segredo de Validação não for preenchido, o sistema tenta usar a credencial webhookSecret como fallback.

Filtros

A seção Filtros permite ignorar mensagens indesejadas antes do processamento.

Campo	Descrição
Campo Obrigatório	Caminho do campo que deve existir e ser truthy no payload para a mensagem ser processada
Ignorar Mensagens Próprias	Caminho do campo booleano que, se `true`, faz a mensagem ser ignorada

Exemplo para o Telegram:

Campo Obrigatório: message.text — ignora updates sem texto (como edições de grupo)
Ignorar Mensagens Próprias: message.from.is_bot — ignora mensagens enviadas por bots

Processamento

O processamento dos webhooks recebidos inclui:

Fila assíncrona com concorrência de 10 mensagens em paralelo
Idempotência via cache Redis com TTL de 1 hora — mensagens com o mesmo ID não são processadas duas vezes
Lock distribuído por ID de mensagem para evitar condições de corrida
Detecção automática de anexo baseada no MIME type:

Padrão MIME	Tipo detectado
`image/*`	IMAGE
`video/*`	VIDEO
`audio/*`	AUDIO
Outros	FILE

Logs

A aba Logs exibe o histórico de todas as operações da Conexão Universal. Você pode filtrar usando os dropdowns Filtrar por tipo e Filtrar por status.

Tipos de log

Tipo	Descrição
Envio	Mensagem enviada para a API externa
Recebimento	Webhook recebido do serviço externo
Teste	Teste de conexão executado

Status

Status	Significado
Sucesso	Operação concluída com sucesso
Erro	Operação falhou
Timeout	Requisição excedeu o tempo limite

Cada log exibe os detalhes da Requisição e da Resposta, incluindo headers, body e código de status.

⚠️ Nota: Os logs possuem TTL de 1 hora e são removidos automaticamente após esse período.

Primeiros Passos

Conexão Universal

API Reference

Recebendo Mensagens

URL do Webhook

Habilitando o recebimento

Mapeamento de Campos

Campos obrigatórios

Campos opcionais

Exemplo

Validação do Webhook

Algoritmos disponíveis

Filtros

Processamento

Logs

Tipos de log

Status

​URL do Webhook

​Habilitando o recebimento

​Mapeamento de Campos

​Campos obrigatórios

​Campos opcionais

​Exemplo

​Validação do Webhook

​Algoritmos disponíveis

​Filtros

​Processamento

​Logs

​Tipos de log

​Status

URL do Webhook

Habilitando o recebimento

Mapeamento de Campos

Campos obrigatórios

Campos opcionais

Exemplo

Validação do Webhook

Algoritmos disponíveis

Filtros

Processamento

Logs

Tipos de log

Status