Configurar um webhook
Caminho: Configurações → Webhooks → Adicionar novo
Visão geral
O webhook permite que você avise outro sistema, como um CRM ou uma automação própria, sempre que um evento acontece no Opa! Suite. Assim, o outro sistema recebe os dados na hora, sem precisar consultar o Opa! Suite de tempos em tempos.
A cada evento escolhido, o Opa! Suite envia uma requisição para o endereço (URL) que você cadastrar, com os dados do evento.
Pré-requisitos
- Permissão Webhooks ativa no grupo de permissões. Por padrão, ela vem ativa só no grupo de administrador.
- Um endereço (URL) do sistema de destino, pronto para receber requisições do tipo POST e responder com sucesso.
Passo a passo
- Acesse Configurações → Webhooks.
- Clique em Adicionar novo. Se ainda não houver webhooks, o botão se chama Adicionar novo webhook. A janela Adicionar webhook abre com três etapas.
- Na etapa Informações principais, preencha:
- Nome: nome para identificar o webhook.
- URL: o endereço que vai receber os avisos.
- Token (opcional): uma senha combinada com o sistema de destino, usada para validar que o aviso veio do Opa! Suite.
- Conteúdo adicional a encaminhar (opcional): um objeto JSON com dados fixos que você quer receber junto com cada aviso, como um identificador da sua empresa.
- Permitir conexão insegura: ative só se o endereço usar um certificado HTTPS inválido ou autoassinado.
- Clique para continuar. Na etapa Validar conexão, o Opa! Suite envia um teste para a URL. Aguarde.
- Na etapa Gatilhos, ative os eventos que devem disparar o webhook. Marque pelo menos um:
- Atendimento movimentado
- Resposta a template interativo
- Cliente inativo durante o atendimento: ao ativar, escolha os Departamentos monitorados e o Tempo máximo de inatividade, em minutos.
- Clique em Adicionar webhook.
Resultado esperado
O webhook aparece na lista, com as colunas Nome, URL e Gatilhos. A partir daí, cada evento escolhido gera um aviso para a URL cadastrada.
Se a URL não responder com sucesso no teste, o cadastro volta para a primeira etapa com a mensagem A URL não respondeu conforme esperado e não conseguimos nos conectar. Verifique as informações fornecidas e tente novamente.
Configurações disponíveis
Para alterar um webhook, clique em Acessar na lista. A tela tem as seções Informações principais e Gatilhos, que podem ser editadas. O botão Testar conexão confere se a URL responde: Conectado com sucesso! ou Não foi possível conectar.
O que dispara cada gatilho
| Gatilho | Quando o aviso é enviado |
|---|---|
| Atendimento movimentado | Quando um atendimento é criado, assumido, transferido para um usuário ou departamento ou encerrado, e quando uma etiqueta, um motivo de atendimento ou uma observação é adicionado ou removido. Os dados incluem o atendimento, o cliente, o contato, o atendente, o departamento, o canal, o status, o protocolo, os motivos, as observações e as etiquetas. |
| Resposta a template interativo | Quando o contato responde a um modelo de mensagem (template) com botões. Os dados incluem a opção escolhida, o contato, o atendimento e o canal. |
| Cliente inativo durante o atendimento | Quando o cliente fica sem responder pelo Tempo máximo de inatividade depois da última mensagem do atendente, em atendimentos dos Departamentos monitorados. Se o cliente responder antes, o aviso é cancelado. |
Token e segurança
Quando o Token está preenchido, cada aviso leva o cabeçalho X-Signature-SHA256, com o token criptografado em SHA-256. O sistema de destino compara esse valor com o SHA-256 do token que ele já conhece para confirmar que o aviso veio do Opa! Suite.
A opção Permitir conexão insegura só faz o Opa! Suite aceitar certificados HTTPS inválidos ou autoassinados. Endereços com http:// são aceitos com ou sem essa opção.
Conteúdo adicional
O JSON informado em Conteúdo adicional a encaminhar é incluído em todos os avisos, junto com os dados do evento. Se o JSON estiver mal formado, aparece JSON inválido.
Problemas comuns
| Sintoma | O que verificar |
|---|---|
| O cadastro volta para a primeira etapa | A URL não respondeu com sucesso ao teste. Confira o endereço e se o sistema de destino está no ar e aceita requisições POST. |
| Aparece Url inválida | O endereço não está num formato válido. Informe a URL completa, com https:// ou http://. |
| Aparece Selecione ao menos um gatilho | Nenhum gatilho foi ativado. Ative pelo menos um. |
| O sistema de destino deixou de receber alguns avisos | O Opa! Suite espera até 10 segundos pela resposta e não reenvia avisos que falharam. Confira se o destino estava fora do ar ou lento nesse período. |
| O teste falha com certificado autoassinado | O botão Testar conexão não considera a opção Permitir conexão insegura. Confira o envio real de um evento. |
Boas práticas
- Prefira endereços com HTTPS e preencha o Token para validar a origem dos avisos.
- Faça o sistema de destino responder rápido e processar os dados depois, para não passar do tempo de espera de 10 segundos.
- Como avisos que falham não são reenviados, trate o webhook como notificação e use a API para conferir dados importantes.
- Ative só os gatilhos que o sistema de destino usa.