Conecte seu sistema e receba eventos da plataforma automaticamente quando algo acontece.
O webhookwebhookO aviso automático que a plataforma envia ao seu sistema toda vez que um evento acontece. é a forma de avisar automaticamente outro sistema sempre que algo importante acontece na plataforma: um protocoloprotocoloO registro de um atendimento, do início ao encerramento. é aberto, um contato é criado, uma tag é alterada. Em vez de alguém da sua equipe replicar essas informações manualmente no seu ERP, CRM ou dashboard, a plataforma envia os dados sozinha, no momento em que o evento ocorre.
É um recurso voltado para quem tem sistema próprio e precisa manter os dados sincronizados. Normalmente quem configura é a pessoa responsável por TI ou integrações, mas o resultado atende toda a operação que depende desses sistemas conversarem entre si.
Como funciona: você informa um endereço (uma URL do seu sistema) e quais eventos quer receber. Quando um desses eventos acontece, a plataforma envia para essa URL um pacote de informações em formato JSONJSONUm formato de texto usado para organizar dados que um sistema envia para o outro.. Seu sistema recebe o pacote e faz o que precisar: atualizar um registro, disparar um alerta, gerar um relatório.
Para usar o webhook, você precisa atender a dois requisitos:
Procurando outra coisa?
Voltar para o inícioPara cadastrar o e-mail, acesse Gerenciar > Parâmetros > Notificações e adicione pelo menos um endereço na seção Alertas por e-mail.
Importante: O último e-mail cadastrado não pode ser removido. Como ele é o canal de aviso de falhas, a exclusão fica bloqueada para você não ficar sem comunicação caso algo dê errado.
Com os requisitos prontos, é hora de cadastrar a URL do seu sistema.
Assim que você confirma, a plataforma envia uma requisição de teste para a URL e mostra o resultado da validação dentro do próprio modal:
Dica: Se a validação falhar várias vezes, confirme com seu desenvolvedor se o servidor está respondendo 200 OK via HTTPS à requisição de teste. Esse é o sinal que a plataforma espera para considerar a URL válida.URL validada não significa webhook ativo. Você precisa ligar o toggle de ativação para a plataforma começar a enviar os eventos.
Na seção Configurações Webhook, clique no toggle ao lado da mensagem O Webhook está inativo. Clique para ativar.
Assim que o webhook é ativado, um aviso confirmando que os eventos serão enviados para o seu sistema assim que ocorrerem aparece no canto da tela. No topo da página, o status passa de Webhook inativo para Webhook ativo.
Atenção: Ativar o webhook não basta. Você também precisa escolher quais eventos quer receber. Se nenhum evento estiver selecionado, nada será enviado, mesmo com o webhook ativo.
Logo abaixo da URL, a seção Eventos de Callback lista todos os tipos de evento que o webhook pode disparar, organizados em dois grupos: Protocolos e Contatos. Cada evento tem seu próprio checkbox e pode ser ativado de forma independente.
São eventos relacionados ao ciclo de vida dos atendimentos.
| Evento | Quando é disparado |
|---|---|
| Abertura | Um novo protocolo é aberto |
| Encerramento | Um protocolo é encerrado |
| Entrada em fila | Um protocolo entra em fila de atendimento |
| Transferência para usuário | Um protocolo é transferido para um atendente |
| Edição de tags | As tags de um protocolo são alteradas |
São eventos relacionados ao cadastro dos contatos da sua base.
| Evento | Quando é disparado |
|---|---|
| Criação | Um novo contato é cadastrado (manualmente, por importação em lote ou por início de conversa com um número ainda não cadastrado) |
| Edição de dados | Os dados de um contato são editados (dados gerais, profissionais ou endereço) |
Clique no checkbox de cada evento que você quer receber. Você pode ativar todos, ativar só alguns ou desativar todos.
Importante: Sempre que você marca ou desmarca um evento, o webhook é desativado automaticamente por segurança. Isso evita que o seu sistema comece a receber (ou pare de receber) eventos sem você perceber. Depois de ajustar a lista, ative o toggle do webhook novamente.
Se você desmarcar todos os eventos, um aviso laranja informa que "todas as opções estão desabilitadas, nenhum dado será enviado", nem mesmo se o webhook estiver ativo. É só uma proteção visual para você não esquecer de marcar pelo menos um.
Ao lado da URL cadastrada, ficam disponíveis dois botões:
A nova URL precisa passar pela validação antes de ser salva, exatamente como na criação.
Ao confirmar, o webhook é removido e os eventos deixam de ser enviados. Você volta para a tela inicial e precisa cadastrar uma nova URL se quiser voltar a usar o recurso.
Atenção: A exclusão é definitiva. Se você excluir e cadastrar a mesma URL depois, vai precisar configurar os eventos do zero.
Se o seu servidor parar de responder ou começar a retornar erros, a plataforma não desiste no primeiro problema. Ela continua tentando enviar os eventos por um período antes de invalidar a URL.
200 OK, a URL é considerada inválida e o webhook é desativado automaticamente.Você é alertado por três caminhos diferentes:
Quando o webhook começa a falhar, a página muda visualmente para chamar a sua atenção:
Dica: O timer mostra o tempo desde a última tentativa bem-sucedida. Use ele como referência para entender o quão urgente é resolver o problema antes de cruzar o limite das 72 horas.
O botão Enviar novamente dispara um teste imediato para a URL. Use ele depois de checar com seu desenvolvedor se o problema foi resolvido no servidor. Dois resultados são possíveis:
Se as 72 horas passarem sem nenhum envio bem-sucedido, a URL é marcada como inválida e o webhook é desativado.
Você recebe um e-mail de aviso e uma notificação na plataforma. A página do webhook entra no estado URL Inválida:
A partir desse ponto, você tem duas opções:
A documentação técnica completa dos webhooks fica em apidocs.maischat.com. Útil para quem vai desenvolver o sistema receptor.
Por que o webhook é desativado toda vez que mudo um evento? É uma proteção. Quando você altera a lista de eventos, o sistema receptor pode não estar preparado para a mudança. A desativação automática força você a confirmar a configuração antes que os disparos comecem.
O que acontece com os eventos que ocorreram enquanto o webhook estava desativado? Eles não são guardados. O webhook só envia eventos que acontecem com ele ativo e com o evento marcado. Se você desligar e religar, o que aconteceu nesse intervalo não volta.
Posso cadastrar mais de uma URL? Hoje não. É permitida apenas uma URL de callback por conta. O suporte a múltiplas URLs está previsto para entregas futuras.
Qual é o tempo de retenção das mensagens em caso de falha? A plataforma tenta reenviar por 72 horas. Respostas não reconhecidas são mantidas por até 120 horas antes de serem descartadas.
O webhook envia eventos de teste?
Sim. Sempre que você cadastra ou edita uma URL, a plataforma envia uma requisição de validação para confirmar que o destino está respondendo. Ela aparece com o campo event igual a validacao.