Usar webhooks con workflows de HubSpot

Usa webhooks en workflows para enviar u obtener información entre HubSpot y otras herramientas externas. Los webhooks tienen múltiples usos. Algunos ejemplos de casos de uso común para emplear webhooks son los siguientes:

• Envío de datos de contacto de HubSpot a otro sistema, como un CRM, cuando ese contacto rellena un formulario concreto en tu sitio.

• Envío de los datos del negocio a un sistema externo de gestión de envíos para crear un pedido de compra.

• Recuperar datos de otro sistema para actualizar tus registros de HubSpot.

Puedes enviar solicitudes POST y GET utilizando workflows. HubSpot regula el tráfico de webhook por separado de otros procesos de workflow. Esto se hace para optimizar el rendimiento del workflow y el rendimiento del webhook. Cuando un webhook es lento o los horarios, 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. Las fallas posteriores se volverán a intentar a intervalos cada vez mayores, con un intervalo máximo de ocho horas entre los 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 el encabezado Reintentar después si está presente. 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 una solicitud POST

1. En tu cuenta de HubSpot, ve a Automatización > Workflows.
2. Para editar un workflow existente, haga clic en el nombre del workflow. O cree un nuevo workflow.
3. En el editor de workflow, haz clic en el + ícono más para agregar una acción.
4. En el panel izquierdo, en la sección Operaciones de datos, selecciona Enviar un webhook.
    

5. Haz clic en el menú desplegable Método y selecciona POST.
6. Introduce la URL del webhook.
   • Las URL de webhook están restringidas a un protocolo de seguridad y deben comenzar con HTTPS.
   • Para solicitar información específica, puede añadir 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.
7. Configura el tipo de autenticación de las solicitudes que se hagan al webhook: Puedes utilizar una firma de solicitud en el encabezado de tu webhook o utilizar una Clave de API:
   • Para utilizar una firma de solicitud en el título de tu webhook:
     • Haz clic en el menú desplegable Tipo de autenticación. A continuación, seleccione Incluir firma de solicitud en la cabecera.
     • A continuación, introduce tu ID de HubSpot App. Aprenda a verificar las firmas de las solicitudes.
   • 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.
     • Cuando se utiliza una clave de API para la autenticación, el nombre de la clave de API y la ubicación de la clave de API utilizada 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. A continuación, seleccione la clave de API.
       • Introducir el nombre de su clave de API.
       • Haga clic en el menú desplegable Ubicación de la clave de API . A continuación, seleccione Parámetros de consulta o Encabezado de solicitud. Más información sobre el uso de las claves de las API en HubSpot.
     • Si estás haciendo una solicitud a las APIs de HubSpot:
       • Haz clic en el menú desplegable Clave de API y selecciona un secreto. El valor secreto debe tener el formato Portador [SU_TOKEN].
       • Define el valor del nombre de la clave de la API como Autorización.
       • Ajuste el valor de la ubicación de la clave de API al encabezado de solicitud.
8. Para incluir todas las propiedades, selecciona Incluir todas las propiedades de [objeto].
9. Para incluir sólo determinadas propiedades:
   • Selecciona Personalizar el cuerpo de la solicitud.
   • Para personalizar el cuerpo de la solicitud utilizando una propiedad de HubSpot, introduce la Clave y selecciona una propiedad. Para agregar otra propiedad, haz clic en Agregar propiedad.
   • Para personalizar el cuerpo de la solicitud utilizando un campo estático, introduce la Clave y el Valor. Para agregar otra propiedad, haz clic en Agregar valor estático.
   • Para eliminar una propiedad o un valor estático, haz clic en el delete icono de papelera.
10. Haz clic en Guardar.

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

Configurar una solicitud GET

1. En tu cuenta de HubSpot, ve a Automatización > Workflows.
2. Para editar un workflow existente, haga clic en el nombre del workflow. O cree un nuevo workflow.
3. En el editor de workflow, haz clic en el + ícono más para agregar una acción.
4. En el panel izquierdo, en la sección Operaciones de datos, selecciona Enviar un webhook.
    

5. Haz clic en el menú desplegable Método y selecciona GET.
6. Introduce la URL del webhook.
   • Las URL de webhook están restringidas a un protocolo de seguridad y deben comenzar con HTTPS.
   • Para solicitar información específica, puede añadir 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.
7. Configura el tipo de autenticación de las solicitudes que se hagan al webhook: Puedes utilizar una firma de solicitud en el encabezado de tu webhook o utilizar una Clave de API:
   • Para utilizar una firma de solicitud en el título de tu webhook:
     • Haz clic en el menú desplegable Tipo de autenticación. A continuación, seleccione Incluir firma de solicitud en la cabecera.
     • A continuación, introduce tu ID de HubSpot App. Aprenda a verificar las firmas de las solicitudes.
   • 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.
     • Cuando se utiliza una clave de API para la autenticación, el nombre de la clave de API y la ubicación de la clave de API utilizada 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. A continuación, seleccione la clave de API.
       • Introducir el nombre de su clave de API.
       • Haga clic en el menú desplegable Ubicación de la clave de API . A continuación, seleccione Parámetros de consulta o Encabezado de solicitud. Más información sobre el uso de las claves de las API en HubSpot.
     • Si estás haciendo una solicitud a las APIs de HubSpot:
       • Haz clic en el menú desplegable Clave de API y selecciona un secreto. El valor secreto debe tener el formato Portador [SU_TOKEN].
       • Define el valor del nombre de la clave de la API como Autorización.
       • Ajuste el valor de la ubicación de la clave de API al encabezado de solicitud.
8. Si estás ajustando una petición GET, puedes utilizar propiedades de HubSpot o añadir valores estáticos como parámetros de consulta: 

9. Para utilizar una propiedad de HubSpot como parámetro de consulta:
   • En la sección Parámetros de consulta , introduzca la Clave y, a continuación, seleccione una propiedad.
   • Para agregar otra propiedad, haz clic en Agregar propiedad.
   • Para eliminar una Propiedad, haga clic en el icono delete eliminar.
10. Para utilizar un valor estático como parámetro de consulta:
    • En la sección Parámetros de consulta , introduce la clave y luego introduce un valor.
    • Para agregar otra propiedad, haz clic en Agregar valor estático.
    • Para eliminar una Propiedad, haga clic en el icono delete eliminar.
11. Haz clic en Guardar.

Ajuste un límite de tarifa para su webhook

Ajuste un límite de velocidad para determinar la rapidez con la que debe ejecutarse la acción webhook. El límite de tarifa también afectará a todas las acciones siguientes del workflow.

1. En tu cuenta de HubSpot, ve a Automatización > Workflows.
2. Haz clic en el nombre del workflow.
3. En el editor de workflow, haz clic en la acción Enviar un webhook.
4. En el panel izquierdo, haz clic en Configurar límite de tarifa para ampliar la sección.
5. Haz clic para activar el interruptor Activar limitación de velocidad . Por opción predeterminada, esta opción está desactivada. 
6. Ajuste su límite de tarifa: 
   • Ejecuciones de acciones: ajuste el número máximo de ejecuciones por periodo de tiempo. 
   • Plazo: ajuste el plazo para su límite de tarifa. Puede ajustar esta franja horaria por Segundos, Minutos u Horas. 

Probar el webhook en HubSpot

Al configurar tu webhook POST o GET, puedes ejecutar una prueba para ver la respuesta del webhook. 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, la clave de API no se mostrará en ninguna solicitud de prueba.

Después de probar su webhook, puede seleccionar los campos que desea enviar para utilizarlos como entradas más adelante en su workflow. Selecciona sólo 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á.

1. En tu cuenta de HubSpot, ve a Automatización > Workflows.
2. Haz clic en el nombre del workflow.
3. En el editor de workflow, haz clic en la acción Enviar un webhook.
4. En el panel izquierdo, haz clic en Probar acción para ampliar la sección.
5. Si estás probando una solicitud POST, el ajuste de la prueba webhook diferirá en función de si has elegido Personalizar el cuerpo de la solicitud o la opción Incluir todas las propiedades [objeto] en la acción webhook.
   • Si ha seleccionado Personalizar el cuerpo de la solicitud, introduzca los valores de prueba de la propiedad para su prueba.
   • Si ha seleccionado Incluir todas las propiedades de [objeto], haga clic en el menú desplegable [objeto] y, a continuación, seleccione un registro con el que realizar la prueba.
6. Haz clic en Probar.
7. Para comprobar los detalles del webhook, selecciona la pestaña Respuesta o Solicitud. En cada pestaña, puede hacer clic en Abrir todo para desplegar todas las secciones, o en Contraer todo para contraer todas las secciones.
   • En la pestaña Respuesta, haz clic en encabezados: o cuerpo: para ampliar cada sección.
   • En la pestaña Solicitud , haz clic en httpHeaders: para ampliar la sección
     
     

Probar tu webhook externamente

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

1. En su navegador, vaya a https://webhook.site y copie la URL única.
2. En el campo URL de webhook de la acción del webhook, pega la URL.
3. Una vez activado el workflow, puede inscribir manualmente un contacto de prueba.
   
   

4. Cuando pruebes tu webhook externamente:
   • Cuando se desencadene la acción del webhook, se enviará un cuerpo de respuesta JSON al webhook 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 contacto. El sistema de recepción puede analizar los datos JSON y usarlos para 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 de propiedad históricos solo se devolverán en workflows basados en contactos. Webhooks utilizados en todos los demás tipos de workflows solo devolverá el valor más reciente.

Verificar firmas de solicitud en webhooks de workflow

Cuando hayas seleccionado Request signature en la sección Authentication de tu acción Trigger a webhook , HubSpot rellenará el webhook con una cabecera X-HubSpot-Signature con un hash SHA-256 de la concatenación del app-secret de tu aplicación, el método HTTP, el URI y el cuerpo sin analizar. Más información en la documentación para desarrolladores.

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

• Ten una cuenta de desarrollador. Si no la tienes, regístrate para abrir una.
• Ten una aplicación. Si no tienes una aplicación, aprende cómo crear una aplicación.
• Debes verificar el valor del 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 workflow. 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.

Para utilizar los datos del webhook conectado:

1. En tu cuenta de HubSpot, ve a Automatización > Workflows.
2. Haz clic en el nombre de tu workflow.
3. Haz clic en el icono más + para agregar una acción.
4. En el panel izquierdo, seleccione una acción que utilice el panel de datos.
5. En el panel de datos, haz clic en el menú desplegable Ver propiedades o salidas de acciones desde y selecciona Desencadenante de webhook. A continuación, puedes utilizar las propiedades del webhook conectado.