## Documentation Index Access the complete documentation index at: https://www.zoho.com/es-mx/books/llms.txt Use this file to discover all available documentation pages before proceeding. # Webhooks Los webhooks facilitan la comunicación con aplicaciones de terceros al enviar notificaciones web instantáneas cada vez que se produce un evento en Zoho Books. Con los webhooks, puede configurar URL HTTP y HTTPS y asociarlas con reglas de flujo de trabajo para automatizar el proceso de notificación. Lea nuestro documento de ayuda sobre [ejemplos de webhooks](/books/help/settings/using-webhook.html) para saber más sobre cuándo y cómo puede usar los webhooks. Para obtener información general sobre los webhooks, visite [webhooks.org](https://webhooks.org). **Escenario:** Supongamos que usa una aplicación de cumplimiento de pedidos por separado para enviar pedidos. Cada vez que se crea una orden de venta en Zoho Books, desea que esa aplicación reciba los detalles del pedido de inmediato. Al configurar un webhook con la URL de la aplicación y asociarlo con una regla de flujo de trabajo, Zoho Books envía los detalles del pedido a la aplicación en cuanto se crea una orden de venta, para que su equipo pueda comenzar con el cumplimiento sin volver a ingresar los datos. ## Crear una webhook Para configurar un webhook: * Vaya a **Configuración** en la esquina superior derecha de la página. * Seleccione **Acciones de flujo de trabajo** en _Automatización_. * En el panel _Acciones de flujo de trabajo_, seleccione **Webhooks**. * Haga clic en **\+ Nuevo Webhook** en la esquina superior derecha. ![Click + New Webhook](/books/help/images/settings/webhooks/plus-new-webhook.png) * Complete los detalles necesarios en los siguientes campos. Nombre del campo Descripción **URL y parámetros** Introduzca la URL (la URL de la API del proveedor de servicios externo) y seleccione el tipo de evento para el que se debe activar el webhook. También puede insertar marcadores de posición haciendo clic en el botón **\+ Nuevo marcador de posición**. Seleccione el tipo de método de API: PUT, POST o DELETE. De forma predeterminada, el sistema selecciona el método POST. **POST**: Solicita que los datos enviados se consideren nuevos. **PUT**: Solicita que los datos enviados se consideren la versión modificada de la versión existente. **DELETE**: Solicita que los datos se eliminen. **Parámetros personalizados** Puede agregar parámetros personalizados en el webhook, como AuthToken, Security Token, API Key, etc., en función de los cuales se agregará la URL. Introduzca el parámetro requerido en **Nombre del parámetro** y el valor correspondiente en **Valor del parámetro**. Si desea agregar varios parámetros, haga clic en **\+ Nuevo parámetro**. **Encabezados HTTP** En la sección Encabezados HTTP, puede incluir cualquier información adicional que desee incluir en la solicitud HTTP. Introduzca una clave en **Nombre del parámetro** e introduzca un valor en **Valor del parámetro**. Haga clic en **\+ Nuevo encabezado** si desea agregar encabezados adicionales. **Preferencias de seguridad** Seleccione cómo desea autorizar el acceso a la URL del proveedor de servicios externo. **General**: Seleccione este tipo si desea crear este webhook con autorización básica, autorización de API o sin ninguna autorización. **Conexiones**: Seleccione este tipo si desea usar una conexión que se creó entre Zoho Books y una aplicación de terceros para autorizar este webhook. También puede asegurar el webhook con un token secreto, que no se puede editar ni ver una vez que se crea el webhook. Marque la casilla **Quiero asegurar este webhook con un token secreto** e introduzca el token secreto en el campo de abajo. Esto ayudará a verificar si el webhook fue enviado desde Zoho Books. Debe ser alfanumérico y tener entre 12 y 50 caracteres. **Cuerpo** En la sección Cuerpo, elija cómo desea enviar los datos. Puede elegir entre los parámetros de cuerpo **Carga útil predeterminada**, **x-www-form-urlencoded** y **Crudo**. **Carga útil predeterminada**: En el formato de carga útil predeterminado, todos los parámetros asociados con el módulo se enviarán al cuerpo de la solicitud en el tipo de contenido de formato application/JSON. **x-www-form-urlencoded**: En el formato x-www-form-urlencoded, los datos se codificarán y enviarán al servidor. **Crudo**: En el formato crudo, puede elegir los parámetros que se envían al cuerpo de la solicitud. El tipo de contenido será application/JSON. * Haga clic en **Guardar y ejecutar** para comprobar si el webhook funciona correctamente, o haga clic en **Guardar** si desea ejecutarlo más tarde. **Nota**: Cuando configura webhooks, todos los detalles de sus contactos en su organización de Zoho Books (nombre, número de teléfono, dirección y dirección de correo electrónico) se compartirán con la URL que desea notificar. * * * ## Asociar webhooks con reglas de flujo de trabajo Los webhooks que cree deben asociarse con reglas de flujo de trabajo para que se activen automáticamente cuando se cumplan las condiciones requeridas. Para asociar webhooks con reglas de flujo de trabajo: * Vaya a **Configuración**. * Seleccione **Reglas de flujo de trabajo** en _Automatización_. * Haga clic en **\+ Nueva regla de flujo de trabajo** en la esquina superior derecha. * Introduzca los detalles necesarios. Consulte [Reglas de flujo de trabajo](/es-mx/books/help/settings/automation/workflow-rules.html). * En [**Acciones**](/es-mx/books/help/settings/automation/workflow-rules.html#add-actions), elija **Webhooks** como _Tipo_ y seleccione el webhook que desea asociar con la regla de flujo de trabajo. * Haga clic en **Guardar**. Ahora, cada vez que se cumplan los criterios, se activará la regla de flujo de trabajo, lo que a su vez activará el webhook. * * * ## Comportamiento de entrega Cuando se activa un webhook, Zoho Books intenta entregarlo a la URL de su punto de conexión. Las siguientes secciones explican cómo se evalúan, reintentan y registran las entregas en los [Registros de flujo de trabajo](/es-mx/books/help/settings/automation/workflow-logs.html). ### Estados de entrega Cada entrega de webhook genera uno de estos estados en los Registros de flujo de trabajo: * **Correcto**: El punto de conexión respondió con un código de estado 2xx dentro del tiempo de espera. * **Error**: La entrega recibió una respuesta distinta de 2xx o se agotó el tiempo de espera. * **Omitido**: No se intentó la entrega, normalmente cuando se alcanza el límite diario. Si se programa un reintento para una entrega con error, la hora del próximo reintento se muestra junto al estado. ### Comportamiento del tiempo de espera El tiempo de espera de conexión está establecido en 5 segundos y el tiempo de espera de lectura en 10 segundos. Si se supera cualquiera de los dos límites, el intento se marca como erróneo. ### Qué cuenta como error Cualquier respuesta distinta de 2xx, incluidas las redirecciones 3xx, los errores de cliente 4xx, los errores de servidor 5xx y los tiempos de espera agotados, se trata como un error y es apta para reintento. Si la URL de su punto de conexión tiene una redirección configurada, actualice la URL del webhook directamente al destino final. ### Directiva de reintento predeterminada Los webhooks con error se reintentan automáticamente exactamente 5 veces antes de marcarse como agotados. Las entregas reintentadas llevan la misma carga útil original, así que diseñe su punto de conexión para que gestione las entregas duplicadas de forma segura. ### Directiva de reintento personalizada Puede configurar hasta 20 intentos de reintento, junto con una opción de método de reintento: **intervalo fijo** (el mismo tiempo de espera entre cada reintento), **aditivo** (el tiempo de espera aumenta en una cantidad fija después de cada reintento) o **multiplicativo** (el tiempo de espera se multiplica por un factor establecido después de cada reintento). Para configurarlo, abra la pestaña **Webhooks** en [Configurar preferencias de error](/es-mx/books/help/settings/automation/workflow-logs.html#configure-failure-preferences) en la página Registros de flujo de trabajo. ### Notificaciones de error Si un webhook falla 20 veces o más de forma consecutiva, se envía una notificación a los destinatarios configurados en la pestaña **Webhooks** en [Configurar preferencias de error](/es-mx/books/help/settings/automation/workflow-logs.html#configure-failure-preferences) en la página Registros de flujo de trabajo. ### Reintento manual Los webhooks agotados se pueden reintentar manualmente desde los [Registros de flujo de trabajo](/es-mx/books/help/settings/automation/workflow-logs.html) en cualquier momento. Los reintentos manuales no cuentan para el límite diario de webhooks de su organización, que varía según su plan de Zoho Books. * * * ## Asegure sus webhooks Asegurar sus webhooks puede ayudar a verificar que los webhooks fueron enviados desde Zoho Books. Para ello, debe configurar su servidor para que escuche los webhooks de Zoho Books. Cuando su servidor recibe un webhook de Zoho Books, se debe generar un valor hash basado en la carga útil y su token secreto. Una vez hecho esto, compruebe si coincide con el valor hash de Zoho Books y valide así la fuente del webhook. Esto puede agregar una capa de seguridad al permitir que su servidor ignore los webhooks de terceros que pretenden originarse en Zoho Books. * * * ## Validar webhooks Cuando su servidor recibe el webhook, se tendrá que generar un valor hash para la carga útil de la misma manera en que Zoho Books lo generó. Esto es necesario para producir el mismo valor hash y validar el webhook. Los siguientes parámetros (si están disponibles) se utilizan para generar el valor hash: * Parámetros de cadena de consulta. * Carga útil predeterminada o carga útil JSON cruda personalizada. * Carga útil x-www-form-urlencoded (pares clave-valor). Construya una cadena ordenando los pares clave-valor de la carga útil en orden alfabético. Los pares deben ordenarse en orden alfabético con respecto a sus claves. **Nota** * Si su webhook contiene **parámetros de cadena de consulta**, asegúrese de que esos pares clave-valor estén ordenados junto con los pares clave-valor de la carga útil. * No puede haber espacios entre los pares clave-valor. Una vez que haya ordenado los pares clave-valor y construido la cadena, agregue el JSON crudo al final de la cadena. **Ejemplos** 1\. **Carga útil predeterminada** Pares clave-valor de los parámetros de cadena de consulta: ``` subscription\_id=90343, name=basic ``` Carga útil predeterminada/JSON crudo: ``` {"created\_date":"2019-03-06","event\_id":"5675"} ``` La cadena construida sería: ``` namebasicsubscription\_id90343{"created\_date":"2019-03-06","event\_id":"5675"} ``` 2\. **x-www-form-urlencoded** Pares clave-valor de los parámetros de cadena de consulta: ``` customer\_name=Brandon, status=active ``` Pares clave-valor de la carga útil x-www-form-urlencoded: ``` addon\_description=Monthly addon, quantity=1 ``` La cadena construida sería: ``` addon\_descriptionMonthly addoncustomer\_nameBrandonquantity1statusactive ``` **Consejo Pro** * Si su carga útil está en el formato x-www-form-urlencoded, toda la cadena debe decodificarse antes de generar el valor hash. * Si uno de los pares clave-valor contiene espacios, los espacios también deben incluirse en la cadena construida. El valor hash se puede calcular aplicando el algoritmo HMAC-SHA256 en esta cadena, junto con el token secreto que se utilizó en Zoho Books. A continuación, puede validar el webhook comprobando si el valor hash calculado desde su lado coincide con el del encabezado (X-Zoho-Webhook-Signature) del webhook de Zoho Books. Puede verificar la firma de su webhook usando los siguientes lenguajes de programación: **JavaScript:** ```sh const crypto = require('crypto'); function verifyWebhook(queryParams, bodyParams, signature, secretKey) { try { const constructedString = constructString(queryParams, bodyParams); const hmac = crypto.createHmac('sha256', secretKey); hmac.update(constructedString); const calculatedSignature = hmac.digest('base64'); return calculatedSignature === signature; } catch (error) { console.error(error); return false; } } function constructString(queryParams, bodyParams) { // Merge and sort keys const allParams = { ...queryParams, ...bodyParams }; const sortedKeys = Object.keys(allParams).sort(); let result = ''; for (const key of sortedKeys) { result += key + allParams[key]; } return result; } ``` **Java:** ```sh import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.util.Map; import java.util.TreeMap; import java.util.Base64; public class Hmacverify { public static boolean verifyWebhook(Map queryParams, Map bodyParams, String signature, String secretKey) { try { String constructedString = constructString(queryParams, bodyParams); Mac sha256HMAC = Mac.getInstance("HmacSHA256"); SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"); sha256HMAC.init(secretKeySpec); byte[] hash = sha256HMAC.doFinal(constructedString.getBytes()); String calculatedSignature = Base64.getEncoder().encodeToString(hash); return calculatedSignature.equals(signature); } catch (Exception e) { e.printStackTrace(); return false; } } private static String constructString(Map queryParams, Map bodyParams) { StringBuilder result = new StringBuilder(); TreeMap sortedParams = new TreeMap<>(queryParams); sortedParams.putAll(bodyParams); for (Map.Entry entry : sortedParams.entrySet()) { result.append(entry.getKey()).append(entry.getValue()); } return result.toString(); } } ``` **Python:** ```sh import hmac import hashlib import base64 def verifyWebhook(queryParams, bodyParams, signature, secretKey): constructedString = constructString(queryParams, bodyParams) calculatedSignature = base64.b64encode(hmac.new(secretKey.encode(), constructedString.encode(), hashlib.sha256).digest()).decode() return calculatedSignature == signature def constructString(queryParams, bodyParams): # Merge and sort query and body parameters allParams = {**queryParams, **bodyParams} sortedParams = sorted(allParams.items()) result = ''.join([key + value for key, value in sortedParams]) return result # Example usage queryParams = {'subscription_id': '90343', 'name': 'basic'} bodyParams = {'created_date': '2019-03-06', 'event_id': '5675'} signature = 'provided-signature' secretKey = 'your-secret-key' verifyWebhook(queryParams, bodyParams, signature, secretKey) ``` * * * ## Configuración de pasarelas SMS Puede configurar webhooks para enviar y recibir alertas de mensajes a través de pasarelas SMS. Todo lo que tiene que hacer es configurar las pasarelas SMS usando la URL y seguir los pasos que se indican a continuación. ### Bulk SMS Bulk SMS es una pasarela SMS popular y es compatible con más de 800 proveedores de redes móviles en todo el mundo. **URL: https://bulksms.vsms.net/eapi/submission/send\_sms/2/2.0?username=`%username%`&password=`%password%`&msisdn=${CONTACT.CONTACT\_MOBILE\_PHONE}&message=%message\_content%** Para configurar la URL para Bulk SMS: * Haga clic en el icono de **Engranaje** en la parte superior derecha y seleccione **Automatización**. * Navegue a la pestaña **Webhooks** y haga clic en **\+ Nuevo Webhook**. * Copie la URL anterior en el campo **URL para notificar**. * Reemplace los marcadores de posición **%username%** y **%password%** en la URL con el nombre de usuario y la contraseña de su cuenta de Bulk SMS. * Escriba su mensaje al final de la URL, es decir, después de “**message=**”. * Reemplace todos los espacios en blanco del contenido de su mensaje por **%20** y todas las comas por **%2C**. ![Configure Bulk SMS](/books/help/images/settings/bulk-sms.png) **Nota:** Si hay otros signos de puntuación en el contenido de su mensaje, puede consultar cómo reemplazarlos con modificadores en [este](https://meyerweb.com/eric/tools/dencoder/) sitio web. Sin embargo, asegúrese de no reemplazar los signos de puntuación que son esenciales para la sintaxis del mensaje. Después de formatear su mensaje con %20 para los espacios en blanco y %2C para las comas, debería verse así: > **URL: https://bulksms.vsms.net/eapi/submission/send\_sms/2/2.0?username=`%username%`&password=`%password%`&msisdn=${CONTACT.CONTACT\_MOBILE\_PHONE}&message=Hello%20${CONTACT.CONTACT\_NAME}.Thank%20you%20for%20the%20purchase%20of%20${INVOICE.INVOICE\_TOTAL}** **De manera similar, se pueden configurar otras pasarelas SMS, siendo solo la URL diferente.** ### SMS-Magic Las pasarelas SMS como SMS-Magic requieren que introduzca parámetros de entidad adicionales para configurar el webhook. Para configurar SMS-Magic: * Introduzca la URL **https://sms-magic.in/smapi/post** en el campo **URL** para notificar. * Haga clic en **\+ Agregar parámetro de entidad**. * Introduzca el siguiente texto en el campo de parámetros: ![Configure SMS Magic](/books/help/images/settings/sms-magic.png) ``` **User_ID** **%Sender_ID** **%Account_ID** **%hashkey%** ``` Reemplace los marcadores de posición en la URL con el User ID, el Sender ID y el Account ID de su cuenta de SMS-Magic. El hashkey se refiere a un valor md5 hash estándar de una cadena que es una concatenación de su User ID, Password, Account ID y Sender ID. **Nota:** Para generar el valor md5 hash, puede visitar [este](https://www.md5hashgenerator.com/) sitio. ### Text Local Text Local requiere un parámetro de entidad y un parámetro personalizado para funcionar. Para configurar Text Local: ![Configure Text Local](/books/help/images/settings/text-local.png) * Introduzca la URL **http://api.textlocal.in/send/** en el campo **URL para notificar**. * Haga clic en **\+ Agregar parámetro personalizado**. * Agregue los parámetros **sender** y **apikey** y reemplace los marcadores de posición en la URL con la información relevante de Text Local. * Haga clic en **\+ Agregar parámetro de entidad**. * Asigne un nombre al parámetro y seleccione las condiciones requeridas en el menú desplegable. Ejemplo: numbers = ${CONTACT.CONTACT\_MOBILE\_PHONE} * Seleccione la casilla **Agregar parámetros definidos por el usuario** e introduzca el mensaje que se enviará junto con todos los marcadores de posición necesarios. * Haga clic en **Guardar**. * * * ## Editar webhooks Si desea actualizar los detalles de un webhook, puede editarlo. Así es como: * Vaya a **Configuración** en la esquina superior derecha de la página. * Seleccione **Acciones de flujo de trabajo** en _Automatización_. * En el panel _Acciones de flujo de trabajo_, seleccione **Webhooks**. * Coloque el cursor sobre el webhook que desea editar, haga clic en el menú desplegable de la derecha y seleccione **Editar**. * Realice los cambios necesarios y haga clic en **Guardar**. * * * ## Filtrar webhooks Para filtrar la lista de webhooks, siga estos pasos: * Vaya a **Configuración** en la esquina superior derecha de la página. * Seleccione **Acciones de flujo de trabajo** en _Automatización_. * En el panel _Acciones de flujo de trabajo_, seleccione **Webhooks**. * En Módulo, seleccione del menú desplegable el módulo para el que se creó el webhook. Según su selección, el webhook correspondiente se mostrará como una lista. ![Filter Webhook](/books/help/images/settings/Automation-FilterWebhook.png) **Nota** * Solo puede crear 1 webhook para cada regla de flujo de trabajo. * El número de webhooks que puede activar por día varía según su plan de Zoho Books. * * * ## Eliminar webhooks **Advertencia:** La eliminación de un webhook es permanente y no se puede deshacer. Si el webhook está asociado con una regla de flujo de trabajo, la regla de flujo de trabajo no se ejecutará. Para eliminar un webhook: * Vaya a **Configuración** en la esquina superior derecha de la página. * Seleccione **Acciones de flujo de trabajo** en _Automatización_. * En el panel _Acciones de flujo de trabajo_, seleccione **Webhooks**. * Coloque el cursor sobre el webhook que desea eliminar y haga clic en el icono **Eliminar**. ![Click the Delete icon](/books/help/images/settings/webhooks/delete-webhook.png) * En la ventana emergente que aparece, haga clic en **Sí**. El webhook se eliminará. Si usó el webhook en una regla de flujo de trabajo, asegúrese de actualizar la regla de flujo de trabajo, ya que es posible que la regla de flujo de trabajo no se active. * * * ## Temas relacionados * [Reglas de flujo de trabajo](/es-mx/books/help/settings/automation/workflow-rules.html) * [Alertas por correo electrónico](/es-mx/books/help/settings/automation/workflow-actions/email-alerts.html) * [Actualizaciones de campo](/es-mx/books/help/settings/automation/workflow-actions/field-updates.html) * [Notificaciones dentro de la aplicación](/es-mx/books/help/settings/automation/workflow-actions/in-app-notifications.html) * [Funciones personalizadas](/es-mx/books/help/settings/automation/workflow-actions/functions.html) * [Horarios](/es-mx/books/help/settings/automation/schedules.html) * [Registros de flujo de trabajo](/es-mx/books/help/settings/automation/workflow-logs.html)