Webhooks do Deskgram 2: eventos e entregas

Visão geral do módulo de webhooks

Webhooks enviam eventos do Deskgram para uma URL escolhida: CRM, serviço de automação ou sua aplicação. São notificações de saída do Deskgram. Não configuram webhook da Telegram Bot API nem criam um canal de comandos de entrada.

Conferido no código em 24 de outubro de 2026.

Antes de começar: o Deskgram precisa estar aberto e o receptor acessível pelo computador do programa. O envio usa POST com JSON. Entregas interrompidas não são retomadas automaticamente após reiniciar.

A configuração pela interface não exige programação. Desenvolvedores do receptor e usuários da API local podem consultar a referência de API.

Configuração rápida

1. Obtenha a URL de entrada no sistema receptor e prepare seu segredo ou token, se necessário.
2. No Deskgram, abra Configurações → Integrações.
3. Clique em Novo, informe nome e Webhook URL.
4. Em Quais ações enviar, selecione os eventos.
5. Em De quais módulos, mantenha todos ou escolha os necessários.
6. Em Conteúdo da requisição, escolha o formato. Comece pelo JSON padrão do Deskgram se o receptor aceitar.
7. Preencha segredo e cabeçalhos extras quando exigidos.
8. Revise Ativar webhook após salvar e clique em Criar webhook.
9. Clique em Testar, abra o Histórico e confira a entrega.
10. Faça uma ação real curta correspondente ao evento e confira o resultado no receptor.

Testar usa configurações salvas. Após alterar URL, segredo, eventos ou campos, salve antes de testar. É possível criar vários endpoints com destinos, eventos e formatos diferentes.

Conectar um CRM

Use a URL de entrada do webhook do CRM, não a página inicial ou painel. Um canal compatível com Deskgram poderia fornecer:

https://crm.example.com/api/v1/channel-webhooks/deskgram/123

Domínio e número são fictícios. Use os valores do seu CRM.

Deskgram reconhece caminhos /channel-webhooks/deskgram/{id} e mostra o campo do segredo CRM, enviado em x-secret. O CRM fornece endereço e segredo separadamente; não se deduz o segredo pela URL.

Em outros CRMs, confira JSON e autorização. Lead CRM não é adaptador universal: campos precisam corresponder ao contrato do receptor.

Para n8n, Make, Zapier ou API própria, copie a URL da etapa receptora e configure os campos esperados. O fluxo de entrada deve estar ativado e acessível.

Escolher eventos

Para transferir mensagens individuais ao CRM, escolha eventos de mensagens. Tarefa concluída, sozinha, não gera uma requisição para cada mensagem.

Terminar a tarefa não prova sucesso de cada ação; contadores e erros variam por módulo. Destinatários ignorados ou falhas de resolução nem sempre geram message.failed. Eventos de itens ignorados não estão disponíveis.

A resposta de lead exige que um manipulador ativo realmente a receba. Criar webhook não ativa escuta contínua nem garante coleta depois do fim da tarefa.

Resultados de tarefas seleciona os três eventos finais; Todos disponíveis, os seis; Limpar remove tudo. Após limpar, escolha os necessários antes de salvar.

Filtro de módulos

O filtro define quais tarefas podem fornecer eventos. Todos os módulos não restringe a origem; Selecionar módulos limita aos escolhidos.

task.completed com spampm significa fim da tarefa de mensagens privadas. message.sent com spampm significa uma mensagem dessa tarefa.

Selecionar módulo não cria novos eventos. Mensagens e respostas em tempo real estão integradas atualmente a spam_pm; escolher outro módulo não adiciona esse comportamento.

Escolher dados da requisição

O conteúdo depende do evento e dos campos salvos. Compare a prévia com os dados enviados no detalhe real.

Campos próprios

Em cada linha, informe o campo esperado à esquerda, a fonte Deskgram à direita e ative o interruptor.

Exemplo hipotético:

Um evento de mensagem poderia produzir:

{  "contact": {    "telegram_id": "123456789",    "username": "example_client"  },  "comment": "Olá!"}

Pontos criam objetos aninhados. Sem valor na fonte, o campo é omitido. Telefone pode faltar: webhook não revela número oculto.

Desativar ou remover todos os campos envia {}, sem substituir pelo evento completo. A prévia não é o dado real de um futuro destinatário; a entrega pode conter menos campos.

O construtor seleciona e renomeia. Não executa JavaScript, cálculos, consultas ao CRM ou cadeias HTTP.

Configurações adicionais

Exemplo:

{  "Authorization": "Bearer YOUR_RECEIVER_TOKEN"}

YOURRECEIVERTOKEN representa o token do receptor, não uma licença Deskgram.

Ao editar pela interface, deixar o campo do segredo salvo vazio preserva o anterior. Seu valor não é mostrado novamente. A REST API tem regras explícitas de limpeza diferentes.

Com segredo, são enviados x-secret, X-Deskgram-Webhook-Secret e X-Deskgram-Signature. A assinatura verifica o corpo, mas o próprio segredo também vai em cabeçalhos. Use HTTPS e evite registrar esses valores. Exemplo na referência.

Testar a conexão

Testar envia webhook.test, inclusive para endpoint desativado. Verifica conexão HTTP e tratamento da requisição de teste, sem iniciar tarefa Telegram.

Não contém task, lead, account ou message. O mapping atual é aplicado; fontes apenas de lead podem resultar em objeto vazio. O receptor deve tratar testes explicitamente. Rejeição por falta de lead pode ser validação comercial: leia o status e a resposta.

Somente HTTP 200–299 conta como sucesso. 302 não serve: redirecionamentos não são seguidos. Informe a URL final.

HTTP 200 indica aceitação HTTP, não criação de lead ou mensagem. Confira o retorno e o registro no CRM.

Histórico e repetição

O histórico mostra entregas recentes. Filtre por receptor e status e atualize a lista.

Detalhes incluem JSON enviado, evento original nos novos registros, resposta, erro, tentativas e datas. Não são captura completa de cada troca HTTP.

Tentativas automáticas

Até três por entrega, com pausas aproximadas de 2 e 4 segundos antes da segunda e terceira, além da espera de rede. Respostas 4xx e 5xx também são repetidas.

Todas mantêm X-Deskgram-Delivery-Id. O receptor deve deduplicar no escopo do remetente para não repetir ação já concluída.

Repetição manual

1. Abra uma entrega com falha.
2. Corrija URL, segredo ou campos se necessário.
3. Salve.
4. Retorne ao registro e clique em Repetir entrega.
5. Confira novo registro e resultado externo.

Só está disponível para error. Cria nova entrega com novo ID e preserva a original.

Novos registros usam evento original e mapping atual. Antigos sem evento original reenviam o JSON salvo sem segunda transformação. URL, segredo e cabeçalhos atuais são usados nos dois casos.

Se o receptor processou mas a resposta se perdeu, repetir pode duplicar a ação. Como a repetição manual muda o ID, o CRM também precisa deduplicação comercial.

Desativar impede novos eventos automáticos, não cancela solicitações em andamento. Testar/Repetir explícitos funcionam desativado. Excluir conserva histórico, mas impede repetição.

Cenários práticos

Mensagens no CRM

Selecione spampm e message.sent, message.failed, lead.replyreceived. Use JSON padrão e segredo do canal compatível. Envie para sua conta de teste, responda e confira ambas as entregas e registros: isso testa eventos reais além da conexão.

Automação ao finalizar tarefa

Selecione task.completed e módulo. Use JSON padrão ou resultado curto. Acrescente task.failed e task.cancelled se precisar lidar com falhas e paradas.

Sua aplicação

Configure endereço, campos e segredo. Receba POST JSON, valide assinatura, salve ou enfileire com confiabilidade e retorne 2xx. Faça processamento longo depois. Veja o contrato HTTP e HMAC.

Resolver problemas

Gerenciamento por agente IA

As ferramentas MCP exigem permissão em Configurações → MCP. Diferenças:

• Criação normalmente dry-run, novo endpoint desativado.
• Apenas HTTPS público; localhost, LAN e HTTP não são aceitos.
• Ação real aplicável de criar, editar, ativar, testar ou repetir mantém regras protegidas nos envios futuros.
• Editar na interface ou desligar MCP não remove as regras.
• Leitura não revela segredo salvo, valores headers nem corpos completos.

Ler, dry-run, desativar e excluir têm regras próprias e não colocam sozinhos um endpoint antigo na política. Consulte MCP.

Limitações

• São avisos de saída, não execução remota arbitrária nem canal permanente de ordens CRM.
• Histórico não é fila automática durável; interrupção ao fechar não retoma automaticamente.
• Somente POST JSON, sem GET, multipart ou texto arbitrário.
• Não garante entrega única nem ordem entre eventos.
• Resultados dependem do módulo e campos podem faltar.
• Contatos, textos, parâmetros e resultados podem sair para o receptor. Escolha destino e dados considerando isso.

Continuar

Baixar Deskgram 2

Próximo passo

• Todos os guias