Webhooks

Explore With AI

• Open in ChatGPT (opens in new tab)
• Open in Claude (opens in new tab)
• Copy for LLM
• View as Markdown (opens in new tab)

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 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.

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.

• Complete los detalles necesarios en los siguientes campos.

• Haga clic en Guardar y ejecutar para comprobar si el webhook funciona correctamente, o haga clic en Guardar si desea ejecutarlo más tarde.

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.
• En Acciones, 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.

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 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 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 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.

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

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:

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:

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<String, String> queryParams, Map<String, String> 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<String, String> queryParams, Map<String, String> bodyParams) {
        StringBuilder result = new StringBuilder();


        TreeMap<String, String> sortedParams = new TreeMap<>(queryParams);
        sortedParams.putAll(bodyParams);

        for (Map.Entry<String, String> entry : sortedParams.entrySet()) {
            result.append(entry.getKey()).append(entry.getValue());
        }

        return result.toString();
    }
}

Python:

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.

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:

<?xml version="1.0"?>
<m:Library xmlns:m="http://screen-magic.com" xmlns="http://www.defns.com">
<userid>**User_ID**</userid>
<senderid>**%Sender_ID**</senderid>
<accountid>**%Account_ID**</accountid>
<hashkey>**%hashkey%**</hashkey>
<message mobilenumber="${CONTACT.CONTACT_MOBILE_PHONE}" >
<![CDATA[${INVOICE.INVOICE_TOTAL}]]>
</message>
</m:Library>

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.

Text Local

Text Local requiere un parámetro de entidad y un parámetro personalizado para funcionar.

Para configurar Text Local:

• 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.

Eliminar webhooks

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.

• 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
• Alertas por correo electrónico
• Actualizaciones de campo
• Notificaciones dentro de la aplicación
• Funciones personalizadas
• Horarios
• Registros de flujo de trabajo

Was this document helpful?

Yes

No

Was this document helpful?

Enter your comments or feedback on this page

Enter your email address

Refresh

Type the characters you see in the image above

By clicking Submit, you agree to our Privacy Policy .

Submit Cancel

Submit

Submit

Thank you for your feedback!