No menu Automações, há a opção Webhook. Nesta funcionalidade, você pode receber comunicação em tempo real das interações de suas comunicações para acompanhar a efetividade de suas automações.
Nesta opção é possível:
- Criar um novo Webhook;
- Editar ou testar um Webhook criado.
⚠️ Atenção: Apenas usuários Administradores podem cadastrar Webhooks, para saber mais acesse a documentação Gerenciar permissões de acesso.
Criação de Endpoint
Dentro do menu Webhook, clique em +Novo Webhook.
A partir daí, é necessário preencher algumas informações em cada uma das telas.
Cadastro
Nesta tela, preencha um nome para o Endpoint, a URL do Webhook, uma pequena descrição com até 160 caracteres.
Para segurança no envio da informação, é importante que a URL indicada seja pública e que responda a requisições HTTP/HTTPS não autenticadas. Também é importante que a URL não esteja num contexto de VPN.
Em seguida, escolha o Content Type, que é o tipo do arquivo que será enviado, e a forma de Autorização, que pode ser via Header (cabeçalho e valor), Basic (usuário e senha) ou OAuth.
Ao selecionar o tipo de Autorização OAuth, alguns campos a mais aparecerão para configurar, veja quais são abaixo:
URL de autorização: informe a URL do servidor que autenticará sua aplicação e fornecerá o token de acesso.
Content Type: defina o formato dos dados enviados na requisição para a URL de autorização. Lembrando que, aqui neste ponto, estamos falando especificamente do processo de autenticação.
Header personalizado: por padrão este campo virá desabilitado, pois não é uma configuração obrigatória. Caso queira usar, é possível habilitar e então preencher com o nome do header e o valor:
Tipo de Permissão (Grant Type): selecione qual o tipo de credencial o autenticador espera entre as opções: Password ou ClientCredentials.
Ao selecionar Password, precisará preencher com Usuário e Senha. Ao selecionar ClientCredentials, precisará preencher com Client ID e Client Secret.
Após preenchimento dos dados, clique em Próximo para seguir.
Notificação
Na etapa de Notificação, é necessário preencher um e-mail válido para recebimento de notificações sempre que houver alterações ou erros. Depois, é só clicar em Próximo.
Canais
A terceira etapa é a de Canais. Nela, você escolhe qual canal será considerado no seu webhook. É possível escolher a opção de todos os canais ou combinações de quais canais quiser. Após a seleção, clique em Próximo.
Eventos
A quarta etapa é a de Eventos. Nesta tela, você pode selecionar todas as jornadas ativas ou optar por escolher algumas específicas. Para escolher as automações, basta utilizar o combo onde são apresentadas todas as disponíveis ou realizar a busca no campo de busca.
Após a seleção de uma automação, as mensagens vinculadas a ela e ao canal já escolhido anteriormente são exibidas. Em cada mensagem, é possível selecionar as interações. É possível escolher todas ou fazer combinações das interações utilizadas.
É possível adicionar mais de uma automação em seu webhook. Abaixo das interações, você encontra um novo combo para poder selecionar outra automação.
Após o término da seleção, clique em Ativar para seguir.
Teste
A última etapa é a de Teste. Por ser bastante importante, é possível testar o webhook a qualquer momento. Porém, isto só poderá ser feito quando o endpoint já estiver ativo.
Clique em Testar para saber se o webhook está funcionando corretamente.
Ao final, clique em Finalizar. A partir daí, seu webhook já está criado, basta aguardar recebimento.
O envio ao endpoint ocorre no momento que os eventos são processados pela plataforma. O serviço tenta enviar os eventos ao endpoint durante um período de sete dias após a primeira tentativa de envio.
O intervalo entre as tentativas de envio é incrementado a cada falha, seguindo a tabela abaixo.
| Número de tentativas | Intervalo |
| 1 | Imediato |
| 2 | 1h |
| 3 | 2h |
| 4 | 3h |
| 5 | 5h |
| 6 | 8h |
| 6 > | Reinício do intervalo |
Após o período de 7 dias, o envio não mais ocorrerá e os dados “perdidos” podem ser solicitados através do atendimento. Os dados serão gerados em uma arquivo no formato .csv e o tempo de geração dependerá do volume em questão.
O retorno dos dados trará diversos campos com as informações solicitadas. É importante compreender o que significa cada um destes campos para melhor entendimento dos dados. Abaixo, segue tabela com os campos, descrições e informações adicionais, quando necessárias.
| Nome do campo | Descrição | Informações adicionais |
| created | É a data/hora que o evento foi processado pela plataforma. | Formato ISO8601 |
| tenantId | Identificador do tenant. | |
| tenantName | Nome do tenant. | |
| journeyId | Identificador da automação. | |
| journeyVersion | Identificador da versão da automação. | |
| journeyName | Nome da automação. | |
| nodeKey | Identificador do canal. | |
| nodeName | Nome do canal. | |
| channelKind | Tipo do canal. | |
| shootingId | Identificador do disparo. | |
| shootingCreated | Data/Hora que o disparo ocorreu na plataforma. | |
| shootingCorrelationId | Identificador único do disparo. | Essa informação é fornecida durante o envio pela API da automação. Deve ser utilizada pelo cliente para identificar o disparo dentro de sua plataforma. |
| tTrackingUrl | Caso seja um evento de clique aqui será apresentada o link clicado. | Apenas para Email, SMS e WhatsApp. |
| trackingIp | Número do IP onde o evento ocorreu. Pode ocorrer para eventos de clique e abertura de e-mail. | Apenas para Email, SMS e WhatsApp. |
| userAgent | Perfil de navegação utilizado para abrir o email. | Apenas para Email, SMS e WhatsApp. Acesse mais informações no Wikipedia. |
| userAgentBrowserFamily | Texto que identifica o navegador onde o evento ocorreu. | |
| userAgentBrowserVersion | Texto que identifica a versão do navegador onde o evento ocorreu. | |
| userAgentOSFamily | Texto que identifica o sistema operacional onde o evento ocorreu. | |
| userAgentOSVersion | Texto que identifica a versão do sistema operacional onde o evento ocorreu. | |
| userAgentDeviceFamily | Texto que identifica o dispositivo onde o evento ocorreu. | |
| carrierName | Nome da operadora do número do telefone que recebeu o SMS. | Essa informação não é fornecida por todas as operadoras. |
| recipient | Destinatário. | eventType |
| eventType | Tipo do evento. | Ver tabela de tipo de eventos abaixo. |
| bounceType | Identifica se é um hard bounce ou soft bounce. | Essa informação ocorre apenas para e-mail. |
| bounceReason | Descrição detalhada do motivo do bounce. | Essa informação ocorre apenas para e-mail. |
| response | Texto de uma eventual resposta do destinatário para um SMS recebido. | Essa informação ocorre apenas para SMS. |
| eventDate | Data do evento em GMT. | Formato ISO8601. |
| movementDate | Data do movimento. | Formato ISO8601. |
| movementFileName | Nome do arquivo do movimento. | |
| movementLot | Lote do movimento. | |
| integrationId | Identificador da requisição feita à API para realização do disparo. | Esse informação é fornecida na resposta da API. |
| integrationCreated | Data da chamada à API realizada para o disparo | Formato ISO8601. |
| integrationProcessingDate | Data que a requisição foi processada pela plataforma. | |
| customerId | Identificador do cliente. | |
| customerName | Nome do cliente. | |
| documentDescription | Descrição do documento. | |
| documentDueDate | Data de vencimento do documento. | Formato ISO8601. |
| ProviderEventId | Identificador único de cada evento. | |
| IsTest | Identifica se é um teste (true) ou não (false). |
Para cada cliente, o relatório irá retornar o tipo de evento realizado em cada um dos canais em que houve interação.
Em cada canal é possível identificar os seguintes eventos:
| SMS | WhatsApp Zenvia | WhatsApp LivePerson | ||
| Processed | Processed | Processed | Processed | Processed |
| Dropped | Dropped | Posted | Read | Delivered |
| Delivered | Delivered | PrintReleased | Delivered | Click (se tiver URL curto) |
| Deferred | Bounce | Printed | Click (se tiver URL curto) | Bounce |
| Bounce | SentToProvider | PrintRestarted | Bounce | Reply |
| Open | Reply | Reply | Dropped | |
| Click | Click | Dropped | ||
| SpamReport | ||||
| Optout |
Para melhor compreensão dos eventos, segue tabela com a descrição de cada um deles:
| Eventos | Descrição |
| Processed | Enviado |
| Dropped | Enviado, porém não entregue por erro |
| Delivered | Recebido |
| Click | Algum link dentro da mensagem foi clicado |
| Bounce | Não entregue |
| Deferred | Entrega adiada temporariamente |
| Open | Aberto pelo destinatário |
| SpamReport | Denúncia de que a mensagem enviada tratava-se de spam |
| Opt-out | Destinatário optou por se descadastrar da lista de recebimento |
| SentToProvider | Enviado ao provedor |
| Reply | Respondido |
| Read | Mensagem lida pelo destinatário |
| PrintReleased | Pronto para impressão |
| Printed | Impresso |
| PrintRestarted | Impressão reiniciada |
Edição de Endpoint
Dentro do menu Webhook, você terá acesso a lista de todos os webhooks criados.
Caso deseje editar alguma informação, clique no nome do Webhook para abrir suas informações.
Você pode alterar todos os campos da tela de Cadastro, mas é fundamental que todos os campos estejam preenchidos.
É possível também alterar o e-mail preenchido na tela Notificação.
Já na etapa Canais, não é possível fazer nenhuma edição. Para essa alteração, indicamos criar um novo Webhook.
Na etapa Eventos, é possível fazer novas seleções de automações e interações.
Por fim, a etapa de Teste, que pode ser executada a qualquer momento. Não se esqueça de clicar em Salvar, na parte inferior da tela de cada etapa, para garantir uma edição com sucesso.
