Webhooks permitem integrar o Zoho Mail a outros aplicativos externos. Um webhook é usado para acionar uma ação em um aplicativo usando eventos em tempo real de um aplicativo externo. Webhooks são de dois tipos: webhooks de entrada e webhooks de saída. Webhooks de entrada são usados para acionar uma ação dentro do Zoho Mail usando eventos em tempo real de aplicativos de terceiros. Com webhooks de saída, seus e-mails de entrada e novas tarefas criadas podem ser configurados para acionar ações em aplicativos externos.

Como isso funciona?

Para configurar uma integração entre o Zoho Mail e qualquer aplicativo de terceiros, você terá que configurar um webhook de entrada em um aplicativo e um webhook de saída no outro aplicativo. Por exemplo, se quiser postar eventos de um aplicativo externo no seu grupo do Streams, as etapas a seguir devem ser realizadas:

1. Configure um webhook de entrada no Zoho Mail.
2. Obtenha o URL do webhook gerado ao criar o webhook de entrada.
3. Configure um webhook de saída no aplicativo de terceiros usando o URL do webhook obtido.

Se você quiser acionar um evento no aplicativo externo quando receber e-mails, será necessário configurar o webhook de saída no Zoho Mail e o webhook de entrada no aplicativo de terceiros.

Webhooks de entrada

Um webhook de entrada permite que você poste o URL de sua escolha quando um evento especificado ocorre em um aplicativo de terceiros. Você pode configurar o webhook de entrada para postar uma mensagem, nota ou tarefa em seu grupo do Streams usando as informações recebidas do aplicativo externo.

Configuração do webhook de entrada

1. Faça login no Zoho Mail
2. Vá para Settings (Configurações) > Integrations (Integrações) > Developer Space
3. Selecione Webhooks de entrada na seção Configurar no menu à esquerda.
4. Clique em Adicionar nova configuração
   
5. Selecione o formato de postagem
   • ​Mail: a atualização do webhook será enviada para sua caixa de entrada como um e-mail.
   • Post/ Notes/ Task (Postagem/Notas/Tarefa): a atualização do webhook será postada no grupo do Streams preferido como uma postagem/nota/tarefa
6. Se você escolheu e-mail na etapa anterior, ignore esta etapa. Ao selecionar postagem/notas/tarefa, insira os seguintes detalhes na página de configuração:
   • Nome de usuário personalizado: este nome será usado para postar no Streams
   • Grupo: o grupo no qual as atualizações serão publicadas
7. Em seguida, clique em Gravar função em Função personalizada se desejar modificar os dados na solicitação POST para se adequar ao formato do webhook de acordo com suas necessidades. Depois de criar a função personalizada, clique em Select custom function (Selecionar função personalizada) para selecionar a função.
   Observação:
   para estabelecer conexões entre qualquer aplicativo de terceiros de sua escolha, use conectores DRE.
8. Clique em Gerar URL e copie o URL criado.
   ​

O URL que foi gerado é usado durante a configuração de um webhook de saída no aplicativo de terceiros de sua escolha.

Pontos a lembrar

• Se você quiser que a postagem do Streams inclua uma @menção, inclua o seguinte no corpo da mensagem:
  • Para @mencionar um membro do grupo, inclua o @ID do e-mail na mensagem. Exemplo: para @mencionar Rebecca, use @rebecca@zylker.com
  • Para @mencionar um grupo, inclua o @grupo na mensagem. O grupo configurado para o webhook será marcado automaticamente.
• O URL do webhook não deve ser divulgado a pessoas não autorizadas. Se expostos, essas pessoas poderão publicar atualizações no seu grupo do Streams.
• Se você gerar novamente o URL do webhook, precisará substituir o URL antigo pelo novo URL em todos os lugares em que ele foi usado.

Webhooks de saída

Um webhook de saída permite configurar e-mails e tarefas para acionar eventos em aplicativos de terceiros. Você pode publicar os detalhes dos e-mails/tarefas que recebe em aplicativos externos. As opções de filtros na configuração permitem que você selecione quais e-mails/tarefas você deseja que atuem como acionadores para o evento.

Configuração do webhook de saída

1. Faça login no Zoho Mail
2. Vá para Settings (Configurações) > Integrations (Integrações) > Developer Space
3. Selecione Webhooks de saída na seção Configurar no menu esquerdo.
4. Clique em Adicionar nova configuração
   
5. Depois de preencher o nome de usuário personalizado e o URL do webhook, você precisa selecionar uma entidade, ou seja, e-mail ou tarefas, que deseja configurar.
   • Nome de usuário personalizado: o nome dado à configuração do webhook
   • URL do webhook: URL obtido a partir da configuração do webhook de entrada no aplicativo de terceiros. As atualizações acionadas pelo e-mail ou pelas tarefas serão publicadas neste URL.
6. Se você selecionar e-mail, poderá pular a próxima etapa. Você deve escolher um tipo de condição de e-mail e uma condição para a qual você precisa que o webhook seja acionado.
   
   • Tipo de condição: escolha como deseja executar as ações de filtro. Para saber mais sobre os filtros, clique aqui.
   • Conditions (Condições): depois de selecionar o tipo de condição de e-mail, informe uma condição desejada. Por exemplo, a condição pode ser De contém rebecca@zylker.com. Para saber mais sobre as condições de e-mail, clique aqui.
   • Tagged emails (E-mails marcados): ao selecionar e-mails marcados, será preciso escolher as marcas na lista suspensa Select tag(s) (Selecionar marcas). Escolha no máximo três marcas somente.
     • A condição Tagged emails (E-mails marcados) seleciona apenas e-mails com marcas específicas (Newsletter, Marketing etc.). Escolha essa opção se quiser que os e-mails marcados com tags específicas acionem o webhook. Depois de selecionar as tags, sempre que um e-mail de entrada for marcado com qualquer uma das tags selecionadas ou quando você marcar um e-mail mais tarde com uma ou mais dessas tags selecionadas, o webhook será acionado. Contudo, ao selecionar Tagged emails (E-mails marcados), não será possível especificar condições adicionais em Conditions (Condições).
   • Meta Only (Somente meta): se esta opção for marcada, somente os detalhes de Subject, From, To, e Time (Assunto, De, Para e Hora) do e-mail serão publicados no aplicativo de terceiros.
     
7. Se você selecionar Tarefas, deverá escolher uma atividade da tarefa para a qual você precisa que o webhook seja acionado e o notifique. O webhook será acionado sempre que a atividade selecionada ocorrer em uma tarefa atribuída a você.
   • Selecionar atividades da tarefa: escolha as atividades para as quais você deseja ser notificado. Uma vez escolhidas, somente as atividades selecionadas nas tarefas atribuídas a você acionarão eventos no aplicativo de terceiros.
   • Selecionar grupo(s): para tarefas, você pode selecionar grupos do Streams específicos, e o webhook será acionado somente quando as atividades de tarefa escolhidas ocorrerem nesses grupos selecionados. Escolha no máximo três grupos apenas.
   • Meta Only (Somente meta): se essa opção for marcada, somente os metadados dos detalhes da tarefa serão postados no aplicativo de terceiros. A diferença entre Full Data (Dados completos) e Meta data (Metadados) dos detalhes da tarefa é informada na tabela abaixo.

     Dados completos	Somente metadados	Descrição
     detentor	detentor	ID de usuário (Zuid) do detentor
     assigneeName	assigneeName	Apelido do detentor
     displayName	displayName	Nome completo do detentor
     título	título	Título da tarefa
     resumo		Descrição da tarefa
     entityId	entityId	ID da tarefa
     entityType	entityType	Representa a entidade. Por exemplo, 3 indica que é uma entidade de tarefa.
     categoryId		ID da categoria
     categoryName		Nome da categoria
     dueDate	dueDate	Valor da data de vencimento em valores numéricos.
     prioridade		Prioridade da tarefa mencionada no número
     parentTaskId		ID da tarefa principal (se a tarefa acionada for uma subtarefa)
     nameSpaceId	nameSpaceId	id do grupo
     groupName	groupName	nome do grupo
     triggerZuid	triggerZuid	ID de usuário da conta que acionou a ação
     status	status	Status mencionado em número
     statusName		Nome do status da tarefa
     ação	ação	Nome da ação da tarefa que é acionada

8. Clique em Gravar função em Função personalizada se desejar modificar os dados na solicitação POST para se adequar ao formato do webhook de acordo com suas necessidades. Depois de criar a função personalizada, clique em Selecionar função personalizada para selecionar a função.
9. Clique em Salvar.

AMOSTRA DE RESPOSTA DO WEBHOOK:

{
"summary": "Oi, Rebecca, compartilhei o conjunto de slides para nossa apresentação de vendas de sexta. Please take a look and do let me know if you have any suggestions. Atenciosamente, Paula",
"sentDateInGMT": 1560866021000,
"subject": "Marketing – Argumento de venda",
"messageId": 1560840837125110000,
"toAddress": ""Rebecca A"<rebecca@zylker.com>",
"folderId": 3881227000000013000,
"zuid": 647772765,
"ccAddress": "",
"size": 55503,
"sender": "Paula",
"receivedTime": 1560840837126,
"fromAddress": "paula@zylker.com",
"html": "<meta /><div><div style="font-family:"Trebuchet ms", Arial, Helvetica, sans-serif;font-size:12pt;"><div>Oi Rebecca,<br /></div><div><br /></div><div>Compartilhei o conjunto de slides para nossa apresentação de vendas de sexta. Dê uma olhada e me mande sugestões.<br /></div><div id=""><div><img src="/zm/ImageDisplay?f=1.png&mode=inline&cid=0.28869215260.3894179596053002321.16b695cdb49__inline__img__src&" width="145" height="145" style="float:left;" /><br /></div><div><br /></div><div><br /></div><div>Regards,<br /></div><div>Paula<br /><br /></div></div><br /><br /><div style="clear:both;"></div></div><br /></div>",
"IntegIdList": "34000000580271,"
}

Proteção de webhooks

É recomendável proteger seus webhooks, pois isso ajuda a determinar se as solicitações realmente se originaram do Zoho Mail. Para permitir que você verifique os webhooks, o Zoho Mail adiciona uma assinatura a todas as suas solicitações do webhook. Isso adiciona uma camada extra de segurança aos webhooks.

Validação de solicitações do webhook

Cada solicitação do webhook contém uma assinatura para fins de verificação. A chave usada para assinar a mensagem é o segredo x-hook. Este segredo é obtido somente do cabeçalho da primeira solicitação do webhook. A assinatura x-hook é encontrada no cabeçalho HTTP de todas as solicitações. O cabeçalho é um resumo básico 64 de um hash HMAC SHA256. O conteúdo com hash deve ser a representação binária do corpo de solicitação completo.

Para verificar a assinatura, será necessário gerar uma assinatura própria usando o segredo x-hook. Você pode então comparar a assinatura gerada com a assinatura no cabeçalho da solicitação para verificar a autenticidade da solicitação.

O código de exemplo para verificar a validade de uma solicitação é fornecido abaixo:

JAVA:

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.servlet.http.HttpServletRequest;

//method to validate webhook request
boolean verifyWebhookRequest(String secret, String payload, HttpServletRequest request) throws Exception
{
Mac mac = Mac.getInstance("HmacSHA2256");
SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
mac.init(secretKey);
String signature = Base64.encodeBase64String(mac.doFinal(payload.getBytes()));
return signature.equals(request.getHeader("X-Hook-Signature"));
}

JAVA SCRIPT:

function VerifyWebhookRequest(request, secret)
{
//secret is x-hook-secret while registering webhook to URL
var crypto = require('crypto');
var headerHash = request.headers['x-hook-signature'];
var createdHash = crypto.createHmac('sha256' , secret).update(request.body).digest('base64');
return headerHash = = = createdHash;
}