Webhook
Los webhooks le permiten integrar Zoho Mail en otras aplicaciones externas. Un webhook se utiliza para activar una acción en una aplicación mediante eventos en tiempo real desde una aplicación externa. Existen dos tipos de webhooks: los webhooks entrantes y los webhooks salientes. Los webhooks entrantes se utilizan para activar una acción dentro de Zoho Mail mediante eventos en tiempo real provenientes de aplicaciones de terceros. Con los webhooks salientes, los correos electrónicos entrantes o las nuevas tareas creadas pueden configurarse para activar acciones en aplicaciones externas.
¿Cómo funciona?
Para configurar una integración entre Zoho Mail y cualquier aplicación de terceros, deberá configurar un webhook entrante en una aplicación y un webhook saliente en la otra. Por ejemplo, si desea publicar eventos desde una aplicación externa en su grupo de Streams, debe realizar los siguientes pasos:
- Configure un webhook entrante en Zoho Mail.
- Obtenga la URL de webhook generada durante la creación del webhook entrante.
- Configure un webhook saliente en la aplicación de terceros mediante la URL de webhook obtenida.
Si desea activar un evento en la aplicación externa cuando reciba correos electrónicos, debe configurar el webhook saliente en Zoho Mail y el webhook entrante en la aplicación de terceros.
Webhooks entrantes
Un webhook entrante le permite publicar en la URL de su elección cuando se produce un evento específico en una aplicación de terceros. Puede configurar el webhook entrante para publicar un mensaje, una nota o una tarea en su grupo de Streams utilizando la información recibida desde la aplicación externa.
Configuración del webhook entrante
- Inicie sesión en Zoho Mail.
- Vaya a ConfiguraciónDeveloper Space. > Integraciones>
- Seleccione Webhooks entrantes en la sección Configurar del menú de la izquierda.
- Haga clic en Agregar nueva configuración
- Seleccione el formato de la publicación
.
- Correo: recibirá un correo electrónico con la actualización de webhook en su bandeja de entrada.
- Publicación/Notas/Tareas: la actualización de webhook se publicará en el grupo de Streams preferido como una publicación, nota o tarea.
- Si eligió Correo en el paso anterior, omita este paso. Si eligió Publicación/Notas/Tareas, ingrese los siguientes detalles en la página de configuración:
- Nombre de usuario personalizado: este nombre se utilizará para publicar en Streams
- Grupo: el grupo en el que se publicarán las actualizaciones
- A continuación, haga clic en Función de escritura en Función personalizada si desea modificar los datos de la solicitud de la publicación para que se ajusten al formato de webhook según sus necesidades. Una vez creada la función personalizada, haga clic en Seleccionar función personalizada para seleccionarla.Nota:
Puede establecer conexiones entre cualquier aplicación de terceros de su elección utilizando Conectores DRE. - Haga clic en Generar URL y copie la URL creada.
La dirección URL que se generó se utiliza durante la configuración de un webhook saliente en la aplicación de terceros de su elección.
Nota:
Solamente los moderadores o el propietario del grupo pueden configurar el webhook entrante para un grupo de Streams.
Puntos para tener en cuenta
- Si desea que las publicaciones en Streams incluyan una mención con @, agregue lo siguiente en el cuerpo del mensaje:
- Para mencionar con un @ a un miembro del grupo, incluya @(ID del correo electrónico) en el mensaje. Ejemplo: Para @mencionar a Rebecca, escriba @rebecca@zylker.com.
- Para mencionar con un @ a un grupo, incluya @grupo en el mensaje. El grupo configurado para el webhook se etiquetará automáticamente.
- La URL del webhook no debe divulgarse a personas no autorizadas. Si se exponen, podrán publicar actualizaciones en su grupo de Streams.
- Si vuelve a generar la URL del webhook, deberá reemplazar la URL anterior por la nueva en todos los lugares en que se utilizó.
Webhooks salientes
Un webhook saliente le permite configurar sus correos electrónicos/tareas para activar eventos en las aplicaciones de terceros. Puede publicar los detalles de los correos electrónicos o las tareas que reciba en las aplicaciones externas. Las opciones de los filtros en la configuración le permiten seleccionar qué correos electrónicos o tareas desea que actúen como activadores para el evento.
Configuración del webhook saliente
- Inicie sesión en Zoho Mail.
- Vaya a ConfiguraciónDeveloper Space. > Integraciones>
- Seleccione Webhooks salientes en la sección Configurar del menú de la izquierda.
- Haga clic en Agregar nueva configuración
- Después de completar el nombre de usuario personalizado y la URL del webhook, debe seleccionar una entidad, es decir, correo o tareas, que desea configurar.
- Nombre de usuario personalizado: el nombre asignado a la configuración del webhook
- URL de webhook: URL obtenida de la configuración del webhook entrante en la aplicación de terceros. Las actualizaciones activadas desde el correo o las tareas se publicarán en esta URL.
- Si selecciona Correo, puede omitir el siguiente paso. Debe elegir un tipo de condición de correo y una condición para la que necesita que se active el webhook.
- Tipo de condición: elija cómo desea ejecutar las acciones del filtro. Para obtener más información sobre los filtros, haga clic aquí.
- Condiciones: después de seleccionar el tipo de condición de correo, proporcione la condición deseada. Por ejemplo, la condición puede ser que “Desde” contenga rebecca@zylker.com. Para obtener más información sobre las condiciones del correo, haga clic aquí.
- Correos electrónicos etiquetados: si selecciona correos electrónicos etiquetados, debe elegir las etiquetas en el cuadro de selección Seleccionar etiquetas. Solo puede elegir un máximo de 3 etiquetas.
- La condición Correos electrónicos etiquetados selecciona solo los correos electrónicos con etiquetas específicas (boletines informativos, marketing, etc.). Seleccione esta opción si desea que los correos electrónicos marcados con etiquetas específicas activen el webhook. Después de seleccionar las etiquetas, cada vez que un correo electrónico entrante se marque con algunas de las etiquetas seleccionadas o cuando marque un correo electrónico de más tarde con una o más de esas etiquetas seleccionadas, se activará el webhook. Sin embargo, no puede especificar Condiciones adicionales si elige Correos electrónicos etiquetados.
- Meta solamente: si marca esta opción, solo se publicarán en la aplicación de terceros los detalles del asunto, del emisor, del destinatario y de la hora del correo electrónico.
- Si selecciona Tareas, debe elegir una actividad de tarea para la cual necesite que se active el webhook y se le notifique. Cada vez que la actividad seleccionada se produzca en una tarea asignada a usted, se activará el webhook.
- Seleccionar actividades de tareas: elija las actividades para las que desea recibir notificaciones. Una vez seleccionada, solo aquellas actividades seleccionadas en las tareas asignadas a usted activarán eventos en la aplicación de terceros.
- Seleccionar grupos: para las tareas, puede seleccionar grupos de Streams en particular y el webhook se activará solo cuando las actividades de tareas que elija se produzcan en esos grupos seleccionados. Solo puede elegir un máximo de 3 grupos.
- Meta solamente: si marca esta opción, solo se publicarán en la aplicación de terceros los metadatos de la tarea. En la siguiente tabla, se muestra la diferencia entre los datos completos y los metadatos de los detalles de la tarea.
Datos completos Metadatos solamente Una descripción. asignatario asignatario ID de usuario (Zuid) del asignatario assigneeName assigneeName Apodo del asignatario displayName (nombre para mostrar) displayName (nombre para mostrar) Nombre completo del asignatario título título Título de la tarea resumen Descripción de la tarea entityId entityId ID de la tarea entityType entityType Representa la entidad. Por ejemplo, el 3 indica que es una entidad de tarea. categoryId ID de la categoría categoryName Nombre de la categoría dueDate dueDate Valor de la fecha de vencimiento en valores numéricos. prioridad Prioridad de la tarea mencionada en el número parentTaskId ID de la tarea principal (si la tarea activada es una tarea secundaria) nameSpaceId nameSpaceId ID del grupo groupName groupName Nombre del grupo triggerZuid triggerZuid ID de usuario de la cuenta que activó la acción estado estado Estado mencionado en números statusName Nombre del estado de la tarea action action Nombre de la acción de tarea que se activa
- Haga clic en Función de escritura en Función personalizada si desea modificar los datos de la solicitud de la publicación para que se ajusten al formato de webhook según sus necesidades. Una vez creada la función personalizada, haga clic en Seleccionar función personalizada para seleccionar la función.
- Haga clic en Guardar.
- Si la URL de webhook utilizada en la configuración no responde durante un período prolongado, el webhook saliente se deshabilitará automáticamente.
- Cuando usted guarda por primera vez una configuración de webhook saliente, se inicia una solicitud POST. La configuración se guardará solo si se recibe una respuesta 200 para la solicitud POST.
EJEMPLO DE RESPUESTA DEL WEBHOOK:
{
"summary": "Hola, Rebecca: compartí los conjuntos de diapositivas para nuestra reunión de presentación del producto del viernes. Eche un vistazo y avíseme si tiene alguna sugerencia. Saludos, Paula",
"sentDateInGMT": 1560866021000,
"subject": "Marketing: Presentación de producto",
"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>Hola, Rebecca:<br /></div><div><br /></div><div>Le compartí el conjunto de diapositivas para nuestra reunión de presentación del producto del viernes. Eche un vistazo y avíseme si tiene alguna sugerencia.<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>Saludos,<br /></div><div>Paula<br /><br /></div></div><br /><br /><div style="clear:both;"></div></div><br /></div>",
"IntegIdList": "34000000580271,"
}
Asegurar webhooks
Se recomienda asegurar sus webhooks, ya que esto ayuda a determinar si las solicitudes se originaron en Zoho Mail. Para permitirle comprobar los webhooks, Zoho Mail agrega una firma a todas sus solicitudes de webhook. Esto agrega una capa adicional de seguridad a sus webhooks.
Validar solicitudes de webhook
Cada solicitud de webhook contiene una firma con fines de verificación. La clave que se utiliza para firmar el mensaje es el x-hook-secret. Este secreto se obtiene solo desde el encabezado de la primera solicitud del webhook. El x-hook-signature se encuentra en el encabezado HTTP de todas las solicitudes. El encabezado es un resumen base 64 de un hash HMAC SHA256. El contenido con hash debe ser la representación binaria del cuerpo completo de la solicitud.
Para comprobar la firma, se le solicitará que genere una firma propia utilizando el x-hook-secret. A continuación, puede comparar la firma generada con la firma en el encabezado de la solicitud para comprobar la autenticidad de la solicitud.
El código de ejemplo para comprobar la validez de una solicitud se indica a continuación:
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;
}