Usar webhooks con workflows de HubSpot

Usa webhooks en workflows para enviar u obtener información entre HubSpot y otras herramientas externas. Los webhooks pueden usarse de muchas formas, y entre los ejemplos de uso más populares, se incluyen los siguientes:

• Publicar datos de contactos de HubSpot a otro sistema, como un CRM, cuando los contactos completan un formulario en tu sitio.

• Enviar datos de negocios a un sistema externo de gestión de envíos para crear un pedido.

• Enviar alertas de chat desde tu sistema externo al flujo de chat de tu empresa para notificar a los empleados que ha ocurrido algo importante.

• Obtener datos de otro sistema para actualizar los registros de HubSpot. 

Puedes enviar solicitudes POST y GET utilizando workflows. HubSpot regula el tráfico de webhooks por separado de otros de los procesos de los workflows. Esto se hace para optimizar el rendimiento de workflow y el del webhook. Cuando un webhook es lento o agota el tiempo de espera, la acción del workflow puede tardar más de lo esperado.

Nota: cuando un webhook falla, HubSpot vuelve a intentar ejecutarlo durante un máximo de tres días, comenzando un minuto después del fallo. Los fallos posteriores se volverán a intentar a intervalos cada vez mayores, con un intervalo máximo de ocho horas entre intentos. Los workflows no reintentarán tras recibir códigos de estado de respuesta de la serie 4XX.
Una excepción a esta regla son los errores de límite de velocidad 429; los workflows reintentarán automáticamente tras recibir una respuesta 429, y respetarán la cabecera Retry-After si está presente. El Retry-After se registra en milisegundos. Para saber qué excepciones se aplican a códigos de error específicos, consulta la documentación para desarrolladores de HubSpot.

Puedes consultar más información sobre los webhooks en la documentación para desarrolladores. Si tienes preguntas sobre una implementación específica, puedes publicarla en los foros de HubSpot para desarrolladores.

Configurar un webhook en un workflow

• En tu cuenta de HubSpot, dirígete a Automatizaciones > Workflows.
• Haz clic en el nombre del workflow.
• Haz clic en el ícono + para agregar una acción.
• En el panel izquierdo, selecciona Enviar un webhook.
• Haz clic en el menú desplegable Método y selecciona POST o GET. 
• Introduce la URL del webhook. Las URL de los webhooks están restringidas a un protocolo de seguridad y deben comenzar con HTTPS. Para solicitar información específica, puedes agregar parámetros de consulta, como ?queryparameter=abc, a la URL del webhook. Si no se han agregado parámetros de consulta, se enviará una solicitud genérica POST o GET. 
• Configura el tipo de autenticación de las solicitudes que se hagan al webhook: 
  • Para utilizar una firma de solicitud en el encabezado del webhook: 
    • Haz clic en el menú desplegable Tipo de autenticación. A continuación, selecciona Incluye la firma de la solicitud en el título.
    • Luego, introduce tu ID de aplicación de HubSpot. Consulta cómo verificar las solicitudes de firma.

• • Para realizar la autenticación, también puedes utilizar una clave de API o una aplicación pública creada a través de una cuenta de desarrollador.

Nota: desde el 30 de noviembre de 2022, las claves de la API de HubSpot están obsoletas y ya no pueden usarse. Puedes seguir utilizando claves de API externas para procesar la autenticación en los workflows de HubSpot.

• • • Cuando se utiliza una clave de API en la autenticación, el nombre de esa clave y su ubicación dependen de cómo esté configurado el webhook. Por razones de seguridad, la clave de API no se mostrará en ninguna solicitud de prueba. Para utilizar una clave de API: 
      • Haz clic en el menú desplegable Tipo de autenticación. Luego, selecciona Clave de API. 

• • • • Introduce el nombre de la clave de la API.
      • Haz clic en el menú desplegable Ubicación de la clave de la API. Luego, selecciona Parámetros de consulta o Encabezado de la solicitud. Más información sobre el uso de las claves de las API en HubSpot.
    • Si estás haciendo una solicitud a una API de HubSpot:
      • Haz clic en el menú desplegable Clave de API y selecciona un secreto. El valor secreto debe tener el formato Bearer [TU_TOKEN].
      • Define el valor del nombre de la clave de la API como Autorización.
      • Define el valor Ubicación de la clave de la API como Encabezado de la solicitud.
• Si estás configurando una solicitud POST, puedes incluir todas las propiedades del registro del CRM o enviar solo propiedades específicas:
  • Para incluir todas las propiedades, en la sección Personalizar el cuerpo de la solicitud, selecciona Incluir todas las propiedades. 
  • Para incluir solo propiedades específicas:
    
    • En la sección Personalizar el cuerpo de la solicitud, selecciona Elegir propiedades específicas.
    • Haz clic en el menú desplegable Elegir propiedad. Luego, haz clic en [objeto] en este workflow y selecciona una propiedad.
    • Para cambiar el nombre de una propiedad del webhook, edita el campo Nombre de la propiedad . Esto solo cambiará el nombre de la propiedad en la solicitud POST, pero no cambiará el nombre de la propiedad ni el nombre interno en HubSpot. 
    • Para agregar otra propiedad, haz clic en Agregar propiedad.
    • Para eliminar una propiedad, haz clic en el icono de la papelera delete.
       

• Si estás configurando una solicitud GET, puedes utilizar propiedades como parámetros de consulta:
  
  • En la sección Parámetros de consulta , haz clic en el menú desplegable Elegir propiedad. Luego, haz clic en [objeto] en este workflow y selecciona una propiedad.
  • Para cambiar el nombre de una propiedad en el parámetro de consulta, edita el campo de texto Nombre de la propiedad. Esto solo actualizará el nombre de la propiedad en la solicitud GET, no actualizará el nombre de la propiedad ni el nombre interno en HubSpot. 
  • Para agregar otro parámetro de consulta, haz clic en Agregar parámetro de consulta.
  • Para eliminar una propiedad, haz clic en el icono de la papelera delete. 
• Haz clic en Guardar.
  
  

Nota: para seleccionar varias salidas, la respuesta debe estructurarse como un objeto JSON.

Personalizar solicitudes POST

Si estás configurando una solicitud POST, puedes incluir todas las propiedades del registro del CRM o enviar solo propiedades específicas:

• Para incluir todas las propiedades, en la sección Personalizar el cuerpo de la solicitud, selecciona Incluir todas las propiedades. 
• Para incluir solo propiedades específicas:
  
  • En la sección Cuerpo de la solicitud, selecciona Personalizar el cuerpo de la solicitud.
  • Introduce la Clave y el Valor.
  • Para cambiar el nombre de una propiedad del webhook, edita el campo de texto Clave. Esto solo cambiará el nombre de la propiedad en la solicitud POST, pero no cambiará el nombre de la propiedad ni el nombre interno en HubSpot. 
  • Para agregar otra propiedad, haz clic en Agregar propiedad.
  • Para eliminar una propiedad, haz clic en el icono de la papelera delete.
    
    

Personalizar solicitudes GET

Si estás configurando una solicitud GET, puedes utilizar propiedades como parámetros de consulta para recuperar datos específicos: 

• En la sección Parámetros de consulta, introduce la Clave y luego selecciona una propiedad.
• Para cambiar el nombre de una propiedad en el parámetro de consulta, edita el campo de texto Nombre de la propiedad. Esto solo actualizará el nombre de la propiedad en la solicitud GET, no actualizará el nombre de la propiedad ni el nombre interno en HubSpot. 
• Para agregar otra propiedad, haz clic en Agregar propiedad.
• Para eliminar una propiedad, haz clic en el icono de la papelera delete. 
• Selecciona un Tipo de autenticación en el menú desplegable.
• Haz clic en Guardar.
  
  

Probar el webhook en HubSpot

Al configurar un webhook POST o GET, puedes ejecutar una prueba para ver su respuesta. Durante la prueba, mientras se envían y recuperan datos de un tercero, los registros existentes en HubSpot no se verán afectados. Si estás utilizando una clave de API para la autenticación, esa clave no se mostrará en ninguna solicitud de prueba.

Después de probar el webhook, puedes seleccionar los campos que se utilizarán como entradas más adelante. Selecciona solo las salidas disponibles en cada respuesta. Si la salida se utiliza en una acción posterior, pero no está disponible en la respuesta, la acción fallará. 

• En el panel lateral, haz clic en Probar acción para ampliar la sección. 
• Haz clic en el menú desplegable Objeto y luego selecciona un Registro con el que hacer la prueba.
• Haz clic en Probar. 
• Para comprobar los detalles del webhook, selecciona la pestaña Respuesta o Solicitud. En cada pestaña, puedes hacer clic en Abrir todo, para ampliar todas las secciones, o en Contraer todo para contraer todas las secciones
  
  • En la pestaña Respuesta, haz clic en encabezados: o en cuerpo: para ampliar cada sección. 
  • En la pestaña Solicitud, haz clic en httpHeaders: para ampliar la sección
    
    

Probar un webhook en un entorno externo

Después de crear un workflow con una acción de webhook, puedes ejecutar una prueba rápida con una URL de webhook ficticia:

• En el navegador, ve a https://webhook.site y copia la URL única.
• En el campo URL de webhook de la acción del webhook, pega la URL.

• Una vez activado el workflow, puedes inscribir manualmente un contacto de prueba. 

Cuando se desencadene la acción del webhook, se enviará a ese webhook un cuerpo de respuesta JSON que contiene toda la información sobre el contacto, incluyendo envíos de formularios, pertenencia a listas y todos los valores de las propiedades de ese contacto. El sistema de recepción puede analizar los datos JSON y usarlos en su propia aplicación.

Si se desencadena una acción de webhook con una solicitud GET, se enviará una solicitud GET genérica, a menos que se hayan aplicado parámetros de consulta adicionales. 

Nota: los valores anteriores de las propiedades solo se devolverán en workflows basados en contactos. Los webhooks utilizados en el resto de tipos de workflows solo devolverán el valor más reciente.

Verificar la solicitud de firmas en los webhooks de workflows

Donde seleccionaste Solicitar firma en la sección Autenticación de la acción Desencadenar un webhook, HubSpot rellenará el webhook con un encabezado de firma X-HubSpot que incluye un código hash SHA-256 de la concatenación del secreto de la aplicación, el método HTTP, la URI y el cuerpo sin analizar. Puedes consultar más información a este respecto en la documentación para desarrolladores.

Para verificar que las solicitudes recibidas en la URL son de HubSpot:

• Debes tener una cuenta de desarrollador. Si no la tienes, regístrate para abrir una.
• Debes tener una aplicación. Si no tienes una aplicación, puedes consultar cómo crear una en este recurso para desarrolladores.
• Debes verificar el valor del código hash de la firma.

Desencadenar workflows a partir de webhooks

Los webhooks pueden utilizarse para activar workflows. Cuando los datos cambian en una aplicación de terceros, esto puede desencadenar un workflows. Más información sobre la activación de workflows desde webhooks.

Utilizar datos de webhook en el panel de datos

Los datos del webhook conectado a tu cuenta pueden utilizarse para determinadas acciones en el panel de datos de .

Para utilizar los datos del webhook conectado a :

• En tu cuenta de HubSpot, dirígete a Automatizaciones > Workflows.
• Haz clic en el nombre de tu workflow.
• Haz clic en el icono + más para añadir una acción.
• En el panel izquierdo, selecciona una acción que utilice el panel de datos .
• En el panel de datos, en Propiedades de inscripción puedes seleccionar una de las propiedades del webhook conectado.