Documentation Index
Fetch the complete documentation index at: https://docs.datacrazy.io/llms.txt
Use this file to discover all available pages before exploring further.
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
}
}
- 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 |
- 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 |
⚠️ Nota: Os logs possuem TTL de 1 hora e são removidos automaticamente após esse período.
