Saltar al contenido principal
Utiliza la herramienta de workflows de HubSpot para automatizar los procesos empresariales y mejorar la eficiencia de los equipos. Puedes crear acciones de workflow personalizadas para integrar tu servicio con los workflows de HubSpot. Después de configurar tu acción personalizada, cuando los usuarios instalen tu aplicación, pueden agregarla a sus workflows. Cuando esos workflows se ejecuten, se enviarán solicitudes HTTPS a la URL configurada con los datos que hayas establecido. Las solicitudes realizadas en la acción personalizada usarán la versión v2 del X-HubSpot-Signature. Más información sobre cómo validar las solicitudes de HubSpot. También puedes pasar directamente a las siguientes secciones: La sección final de este artículo proporciona varios ejemplos de acciones personalizadas.

​
Antes de comenzar

​
Definir la acción personalizada

Para crear una acción de workflow personalizada, deberás definir la acción usando los siguientes campos. Esto también especifica el formato de solicitud para solicitudes procedentes de HubSpot, así como el manejo de respuestas de tu servicio.
  • actionUrl: la URL donde se envía una solicitud HTTPS cuando se ejecuta la acción. El cuerpo de la solicitud contiene información sobre a nombre de qué usuario se está ejecutando la acción y qué valores se ingresaron para los campos de entrada.
  • objectTypes: con qué objetos del CRM se puede utilizar esta acción.
  • published: Por opción predeterminada, las acciones personalizadas se crean en un estado no publicado. Las acciones no publicadas solo son visibles en el portal para desarrolladores asociado a tu aplicación HubSpot. Para que tu acción personalizada sea visible para los usuarios, actualiza la bandera publicada en tu definición de acción a verdadero.
  • inputFields: las entradas o inputs que recibe la acción. Estas serán completadas por el usuario.
  • inputFieldDependencies: estas reglas definen las relaciones entre dos o más inputs, basándose en su dependencyType, como en este ejemplo de aquí. Puedes usar las siguientes opciones de dependencyType:
    • SINGLE_FIELD: estas reglas permiten que los campos se atenúen hasta que otros campos cumplan con condiciones específicas. Utilízalo para asegurarte de que un campo se rellena previamente antes de permitir que los visitantes sigan rellenando el resto del formulario. Los campos controladores (principal) proporcionarán valores a los campos dependientes (secundarios) correspondientes.
    • CONDITIONAL_SINGLE_FIELD: estas reglas permiten que los campos se oculten hasta que otros campos cumplan con condiciones específicas. Utilízalo para mostrar u ocultar campos específicos basándote en una selección previa. Por ejemplo, si tu negocio es una pastelería, puedes añadir una casilla de verificación para preguntar a los visitantes si les gusta la tarta y, solo si se selecciona la casilla de verificación, mostrar un campo para preguntar qué sabor de tarta les gusta.
  • outputFields: los valores que se mostrarán en la acción que se pueden usar más tarde en el workflow. Una acción personalizada puede tener cero, una o muchas salidas.
  • objectRequestOptions: propiedades del objeto inscrito incluidas en la carga útil de actionUrl.
  • labels: copia que describe al usuario lo que representa los campos de la acción y lo que hace la acción. Se requieren etiquetas en inglés, pero estas también pueden especificarse en cualquiera de los siguientes idiomas compatibles:
    • Francés (fr)
    • Alemán (de)
    • Japonés (ja)
    • Español (es)
    • Portugués - Brasil (pt-br)
    • Neerlandés (nl)
    • Polaco (pl)
    • Sueco (sv)
    • Italiano (it)
    • Danés - Dinamarca (da_dk)
    • Finés (fi)
    • Noruego (no)
    • Chino tradicional - Taiwán (zh-tw)
  • executionRules: una lista de definiciones que puedes especificar para exponer errores de tu servicio al usuario que crean el workflow.
  • functions: fragmentos de código que se ejecutan para transformar la carga útil que se envía a una url o transformar la respuesta desde esa url.

​
Ejemplo de definición de acción personalizada

//
{
  "actionUrl": "https://webhook.site/94d09471-6f4c-4a7f-bae2-c9a585dd41e0",
  "objectTypes": ["CONTACT"],
  "inputFields": [
    {
      "typeDefinition": {
        "name": "staticInput",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"],
      "isRequired": true
    },
    {
      "typeDefinition": {
        "name": "objectInput",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["OBJECT_PROPERTY"],
      "isRequired": true
    },
    {
      "typeDefinition": {
        "name": "optionsInput",
        "type": "enumeration",
        "fieldType": "select",
        "optionsUrl": "https://webhook.site/94d09471-6f4c-4a7f-bae2-c9a585dd41e0"
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    }
  ],
  "inputFieldDependencies": [
    {
      "dependencyType": "SINGLE_FIELD",
      "dependentFieldNames": ["objectInput"],
      "controllingFieldName": "staticInput"
    }
  ],
  "outputFields": [
    {
      "typeDefinition": {
        "name": "myOutput",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    }
  ],
  "objectRequestOptions": {
    "properties": ["email"]
  },
  "labels": {
    "en": {
      "inputFieldLabels": {
        "staticInput": "Static Input",
        "objectInput": "Object Property Input",
        "optionsInput": "External Options Input"
      },
      "actionName": "My Extension",
      "actionDescription": "My Extension Description",
      "appDisplayName": "My App Display Name",
      "actionCardContent": "My Action Card Content"
    }
  },
  "functions": [
    {
      "functionType": "POST_ACTION_EXECUTION",
      "functionSource": "exports.main = (event, callback) => {\r\n  callback({\r\n    outputFields: {\r\n      myOutput: \"example output value\"\r\n    }\r\n  });\r\n}"
    },
    {
      "functionType": "POST_FETCH_OPTIONS",
      "functionSource": "exports.main = (event, callback) => {\r\n  callback({\r\n    \"options\": [{\r\n        \"label\": \"Big Widget\",\r\n        \"description\": \"Big Widget\",\r\n        \"value\": \"10\"\r\n      },\r\n      {\r\n        \"label\": \"Small Widget\",\r\n        \"description\": \"Small Widget\",\r\n        \"value\": \"1\"\r\n      }\r\n    ]\r\n  });\r\n}"
    }
  ]
}
La definición anterior mostrará lo siguiente en la herramienta de workflows:
Hay dos tipos de llamadas realizadas para acciones de workflow personalizadas:
  • Recuperaciones de opciones de campo: se completa una lista de opciones válidas cuando un usuario está configurando un campo. Aprende más sobre el uso de las recuperaciones de opciones de campo para obtener campos de datos externos.
  • Solicitud de ejecución de acción: se realiza cuando una acción se ejecuta por un workflow que incluye tu acción personalizada.

​
Funciones

Las funciones son fragmentos de código utilizados para modificar las cargas útiles antes de enviarlas a una API. También puedes usar funciones para analizar los resultados de una API. Las funciones de HubSpot están respaldadas por AWS Lambda. En el siguiente código:
  • event contiene los datos que se pasan a la función
  • exports.main es el método que se llamará cuando se ejecute la función.
  • La función callback se puede utilizar para devolver un resultado.
El código debe tener el siguiente formato: 
exports.main = (event, callback) => {
  callback({
    "data": {
      "field": "email",
      "phone": "1234567890"
    }
  });
}
Al configurar una función, el formato functionSource estará en cadena. Asegúrate de que los caracteres del código tengan secuencia de escape. Generalmente, la definición de una función seguirá el formato: 
//
{
  "functionType": "PRE_ACTION_EXECUTION",
  "functionSource": "exports.main = (event, callback) => {\r\n  callback({\r\n    \"data\": {\r\n      \"field\": \"email\",\r\n      \"phone\": \"1234567890\" \r\n    }\r\n  });\r\n"
}

​
Función de ejemplo

En el siguiente ejemplo, examina el código de input, la función utilizada y el output producido. Función de input: 
//
{
  "callbackId": "ap-102670506-56777914962-11-0",
  "origin": {
    "portalId": 102670506,
    "actionDefinitionId": 10860211,
    "actionDefinitionVersion": 1,
    "extensionDefinitionId": 10860211,
    "extensionDefinitionVersionId": 1
  },
  "context": {
    "source": "WORKFLOWS",
    "workflowId": 192814114
  },
  "object": {
    "objectId": 614,
    "objectType": "CONTACT"
  },
  "inputFields": {
    "widgetOwner": "10887165",
    "widgetName": "My Widget Name"
  }
}
Función utilizada: 
//
exports.main = (event, callback) => {
  callback({
    "data": {
      "myObjectId": event["object"]["objectId"],
      "myField": event["inputFields"]["widgetName"]
    }
  });
}
Output esperado: 
//
{
  "data": {
    "myObjectId": 614,
    "myField": "My Widget Name"
  }
}

​
Campos de input

Las definiciones de los campos de entrada se ajustarán al siguiente formato:
  • name: el nombre interno del campo de entrada, separado de su etiqueta. La etiqueta que se muestra en la interfaz de usuario debe definirse utilizando la sección de etiquetas de la definición de acción personalizada.
  • type: el tipo de valor requerido por la entrada.
  • fieldType: cómo se debe representar el campo de entrada en la interfaz de usuario. Los campos de input imitan las propiedades de CRM. Obtén más información sobre combinaciones válidas de type y fieldType
  • supportedValueTypes tiene dos valores válidos:
    • OBJECT_PROPERTY: el usuario puede seleccionar una propiedad del objeto inscrito o una salida de una acción anterior para usarla como valor del campo.
    • STATIC_VALUE: debe usarse en todos los demás casos. Indica que el usuario debe introducir un valor por sí mismo.
  • isRequired: determina si el usuario debe dar un valor para esta entrada o no
Las definiciones de los campos de entrada deben tener el siguiente formato: 
//
{
  "typeDefinition": {
    "name": "staticInput",
    "type": "string",
    "fieldType": "text"
  },
  "supportedValueTypes": ["STATIC_VALUE"],
  "isRequired": true
}
También puedes codificar opciones para que el usuario seleccione: 
//
{
  "typeDefinition": {
    "name": "widgetColor",
    "type": "enumeration",
    "fieldType": "select",
    "options": [
      {
        "value": "red",
        "label": "Red"
      },
      {
        "value": "blue",
        "label": "Blue"
      },
      {
        "value": "green",
        "label": "Green"
      }
    ]
  },
  "supportedValueTypes": ["STATIC_VALUE"]
}

​
Uso de datos externos

En lugar de incluirlo en el código de las solicitudes, también puedes obtener datos externos con campos de datos externos. Por ejemplo, puedes obtener una lista de proyectos de reuniones o una lista de productos para que sirvan como entradas.

​
Nota:

Para pasar datos de input a otros inputs, debes definir la relación usando inputFieldDependencies. Más información sobre cómo definir una acción personalizada.
El campo de input debe tener el siguiente formato: 
//
{
  "typeDefinition": {
    "name": "optionsInput",
    "type": "enumeration",
    "fieldType": "select",
    "optionsUrl": "https://your-url-here.com"
  },
  "supportedValueTypes": ["STATIC_VALUE"]
}
La carga enviada a optionsURL tendrá el siguiente formato: 
//
{
  "origin": {
    "portalId": 1,
    "actionDefinitionId": 2,
    "actionDefinitionVersion": 3
  },

  "objectTypeId": "0-1",
  "inputFieldName": "optionsInput",
  "inputFields": {
    "widgetName": {
      "type": "OBJECT_PROPERTY",
      "propertyName": "widget_name"
    },
    "widgetColor": {
      "type": "STATIC_VALUE",
      "value": "blue"
    }
  },

  "fetchOptions": {
    "q": "option label",
    "after": "1234="
  }
}
CampoDescripción
portalIdEl ID de la cuenta de HubSpot.
actionDefinitionIdID de definición de la acción personalizada.
actionDefinitionVersionVersión de definición de acción personalizada.
objectTypeIdEl tipo de objeto que se está utilizando en la acción del workflow.
inputFieldNameEl campo de input para el obtener opciones.
inputFieldsLos valores de los campos que ya ha rellenado el usuario del workflow.
qLa consulta de búsqueda proporcionada por el usuario. Debe utilizarse para filtrar las opciones devueltas. Solo se incluirá si la opción anterior ha devuelto searchable: true y el usuario ha introducido una consulta de búsqueda.
afterEl cursor de paginación. Este será el mismo cursor de paginación que devolvió la opción anterior; se puede utilizar para llevar un registro de las opciones que ya se han obtenido.
La respuesta esperada debe tener el siguiente formato: 
//
{
  "options": [
    {
      "label": "Big Widget",
      "description": "Big Widget",
      "value": "10"
    },
    {
      "label": "Small Widget",
      "description": "Small Widget",
      "value": "1"
    }
  ],

  "after": "1234=",
  "searchable": true
}
CampoDescripción
qEl cursor de paginación. Si se proporciona, la aplicación de workflows mostrará un botón para cargar más resultados al final de la lista de opciones cuando el usuario seleccione una opción, y cuando se cargue la siguiente página, este valor se incluirá en la carga útil de la solicitud fetchOptions.after. Este campo es opcional.
afterEl valor predeterminado es false. Si es true, la aplicación de workflows mostrará un campo de búsqueda para que el usuario pueda filtrar las opciones disponibles mediante una consulta de búsqueda. Cuando se introduzca una consulta de búsqueda, las opciones se volverán a introducir con ese término de búsqueda en la carga útil de la solicitud en fetchOptions.q. Este campo es opcional.
En el código anterior, ten en cuenta que se está configurando la paginación para limitar el número de opciones devueltas. Esto le indica al workflow que puede cargar más opciones.Además, la lista de opciones se puede buscar al incluir searchable:true.

​
Modificar datos externos

Para gestionar los datos externos, puedes incluir dos ganchos para personalizar el ciclo de vida de la opción de búsqueda de campos:
  • PRE_FETCH_OPTIONS: una función que configura la carga útil enviada desde HubSpot.
  • POST_FETCH_OPTIONS: una función que transforma la respuesta de tu servicio en un formato que sea entendido por HubSpot.

​
PRE_FETCH_OPTIONS

Cuando se incluya, esta función se aplicará a cada campo de input. Puedes aplicarlo a un campo de input específico agregando un id en la definición de la función. 
//
{
  "functionType": "PRE_FETCH_OPTIONS",
  "functionSource": "...",
  "id": "inputField"
}
La carga enviada desde HubSpot tendrá el siguiente formato: 
//
{
  "origin": {
    "portalId": 1,
    "actionDefinitionId": 2,
    "actionDefinitionVersion": 3
  },

  "inputFieldName": "optionsInput",
  "webhookUrl": "https://myapi.com/hubspot/widget-sizes",
  "inputFields": {
    "widgetName": {
      "type": "OBJECT_PROPERTY",
      "propertyName": "widget_name"
    },
    "widgetColor": {
      "type": "STATIC_VALUE",
      "value": "blue"
    },

    "fetchOptions": {
      "q": "option label",
      "after": "1234="
    }
  }
}
CampoDescripción
portalIdEl ID de la cuenta de HubSpot.
actionDefinitionIdID de definición de la acción personalizada.
actionDefinitionVersionVersión de definición de acción personalizada.
objectTypeIdEl tipo de objeto que se está utilizando en la acción del workflow.
inputFieldNameEl campo de input para el obtener opciones.
inputFieldsLos valores de los campos que ya ha rellenado el usuario del workflow.
qLa consulta de búsqueda proporcionada por el usuario. Debe utilizarse para filtrar las opciones devueltas. Solo se incluirá si la opción anterior ha devuelto searchable: true y el usuario ha introducido una consulta de búsqueda.
afterEl cursor de paginación. Este será el mismo cursor de paginación que devolvió la opción anterior; se puede utilizar para llevar un registro de las opciones que ya se han obtenido.
La respuesta debe tener el siguiente formato: 
//
{
  "webhookUrl": "https://myapi.com/hubspot",
  "body": "{\"widgetName\": \"My new widget\", \"widgetColor\": \"blue\"}",
  "httpHeaders": {
    "My-Custom-Header": "header value"
  },
  "contentType": "application/json",
  "accept": "application/json",
  "httpMethod": "POST"
}
CampoDescripción
webhookUrlLa URL del webhook para que HubSpot la pueda llamar.
bodyEl formato del cuerpo de la solicitud. Esto es opcional.
httpHeadersUn mapa de encabezados con solicitudes personalizadas para agregar. Esto es opcional.
contentTypeEl Content-Type de la solicitud. El valor predeterminado es application/json. Esto es opcional.
acceptEl tipo Accept de la solicitud. El valor predeterminado es application/json. Esto es opcional.
httpMethodEl método HTTP con el que realizar la solicitud. El valor predeterminado es POST, pero otros valores válidos son GET, POST, PUT, PATCH y DELETE. Esto es opcional.

​
POST_FETCH_OPTIONS

Para analizar la respuesta según los campos de datos externos, usa una función POST_FETCH_OPTIONS. La definición de una función POST_FETCH_OPTIONS es la misma que una función PRE_FETCH_OPTIONS. Cuando se definen opciones externas para la obtención de datos, se mostrará un menú desplegable en las opciones de input para la acción. 
//
{
  "functionType": "POST_FETCH_OPTIONS",
  "functionSource": "...",
  "id": "inputField"
}
La función de input tendrá el siguiente formato: 
//
{
  // The requested field key
  "fieldKey": "widgetSize",

  // The webhook response body from your service
  "responseBody": "{\"widgetSizes\": [10, 1]}"
}
La función de output tendrá el siguiente formato: 
//
{
  "options": [
    {
      "label": "Big Widget",
      "description": "Big Widget",
      "value": "10"
    },
    {
      "label": "Small Widget",
      "description": "Small Widget",
      "value": "1"
    }
  ]
}

​
Campos de output

Utiliza los campos de output para generar valores para usar en otras acciones de la acción personalizada. La definición de los campos de salida es similar a la definición de los campos de entrada:
  • name: cómo se hace referencia a este campo en otras partes de la acción personalizada. La etiqueta que se muestra en la interfaz de usuario debe definirse utilizando la sección de `labels` de la acción personalizada
  • type: el tipo de valor requerido por la entrada.
  • fieldType: es cómo se debe representar el de entrada en la interfaz de usuario. Los campos de input imitan las propiedades de CRM. Obtén más información sobre combinaciones válidas de type y fieldType
El campo de output debe tener el siguiente formato: 
//
{
  "outputFields": [
    {
      "typeDefinition": {
        "name": "myOutput",
        "type": "string",
        "fieldType": "text"
      }
    }
  ]
}
Cuando se utiliza un campo de output, los valores se analizan a partir de la respuesta de actionURL. Por ejemplo, puedes copiar los campos de output en una propiedad existente en HubSpot. **
**

​
Etiquetas

Utiliza etiquetas para agregar texto a tus outputs o inputs en el editor del workflow. Las etiquetas se cargan en el servicio de idiomas de HubSpot y pueden tardar unos minutos en mostrarse. Los portales configurados para diferentes regiones o idiomas mostrarán la etiqueta en el idioma correspondiente, si está disponible.
  • labels: copia que describe al usuario lo que representa los campos de la acción y lo que hace la acción. Se requieren etiquetas en inglés, pero estas también pueden especificarse en cualquiera de los siguientes idiomas compatibles: Francés (fr), Alemán (de), Japonés (ja), Español (es), Portugués (pt-br), y Holandés (nl).
  • actionName: el nombre de la acción que aparece en el panel Elegir una acción en el editor de workflows.
  • actionDescription: una descripción detallada de la acción que se muestra cuando el usuario está configurando la acción personalizada.
  • actionCardContent: una descripción resumida que se muestra en la tarjeta de la acción.
  • appDisplayName: El nombre de la sección en el panel “Elegir una acción” donde se muestran todas las acciones de la aplicación. Si appDisplayName se define para múltiples acciones, se utiliza la primera que se encuentre.
  • inputFieldLabels: un objeto que mapea las definiciones de inputFields a las etiquetas correspondientes que el usuario verá cuando configure la acción.
  • outputFieldLabels: un objeto que mapea las definiciones de outputFields a las etiquetas correspondientes que se muestran en la herramienta de workflows.
  • inputFieldDescriptions: un objeto que mapea las definiciones de inputFields a las descripciones debajo de las etiquetas correspondientes.
  • executionRules: un objeto que asigna las definiciones de tus executionRules a los mensajes que se mostrarán para los resultados de la ejecución de acciones en el historial del workflow. Hay una sección separada en estos documentos para las reglas de ejecución.
Las definiciones de las etiquetas deben tener el siguiente formato: 
// {
  "labels":{
    "en":{
      "actionName":"Create Widget",
      "actionDescription":"This action will create a new widget in our system. So cool!",
      "actionCardContent":"Create widget {{widgetName}}",
      "appDisplayName":"My App Display Name",
      "inputFieldLabels":{
        "widgetName":"Widget Name",
        "widgetOwner":"Widget Owner"
      },
      "outputFieldLabels":{
        "outputOne":"First Output"
      },
      "inputFieldDescriptions":{
        "widgetName":"Enter the full widget name. I support <a href=\"https://hubspot.com\">links</a> too."
      },
      "executionRules":{
        "alreadyExists":"The widget with name {{ widgetName }} already exists"
      }
    }
  }
}

​
Ejecución

Cuando se ejecuta una ejecución, se envía una solicitud https al actionUrl.
  • callbackId: un ID único para la ejecución específica. Si la ejecución de la acción personalizada está bloqueando, utiliza este ID.
  • object: los valores de las propiedades solicitadas en objectRequestOptions.
  • InputFields: los valores de las entradas que el usuario ha rellenado.
La carga útil de ejecución se formateará de la siguiente manera: 
// {
  "callbackId": "ap-102670506-56776413549-7-0",
  "origin": {
    "portalId": 102670506,
    "actionDefinitionId": 10646377,
    "actionDefinitionVersion": 1
  },
  "context": {
    "source": "WORKFLOWS",
    "workflowId": 192814114
  },
  "object": {
    "objectId": 904,
    "properties": {
      "email": "[email protected]"
    },
    "objectType": "CONTACT"
  },
  "inputFields": {
    "staticInput": "My Static Input",
    "objectInput": "995",
    "optionsInput": "1"
  }
}
La respuesta esperada debe tener el siguiente formato: 
//
{
  "outputFields": {
    "myOutput": "Some value",
    "hs_execution_state": "SUCCESS"
  }
}
Al observar la respuesta de ejecución:
  • outputFields: los valores de los campos de salida definidos anteriormente. Estos valores se pueden utilizar en acciones posteriores.
  • hs_execution_state: un valor especial opcional que se puede agregar a outputFields. No es posible especificar un reintento, solo se pueden agregar los siguientes valores:
    • LISTO
    • FAIL_CONTINUE
    • BLOQUEAR
    • ASINCRÓNICA
SUCCESS y FAIL_CONTINUE indican que la acción se ha completado y que el workflow debe pasar a la siguiente acción a ejecutar. Si no se especifica ningún estado de ejecución, se utilizarán códigos de estado para determinar el resultado de una acción:
  • Códigos de estado 2xx: la acción se ha completado correctamente.
  • Códigos de estado 4xx: la acción ha fallado. La excepción son los códigos de estado Tasa limitada 429, que se vuelven a tratar como reintentos y se respeta el título Reintentar después.
  • Códigos de estado 5xx: hubo un problema temporal con el servicio y la acción se volverá a intentar más tarde. Se utiliza un sistema de retroceso exponencial para los reintentos. Los reintentos continuarán hasta 3 días antes de fallar.

​
Funciones de ejecución

Utiliza las funciones de ejecución para darle formato a los datos antes de enviarlos a actionURL y analizar los datos de actionURL. Hay dos tipos de funciones de ejecución:
  • PRE_ACTION_EXECUTION
  • POST_ACTION_EXECUTION

​
Función PRE_ACTION_EXECUTION

Utiliza las funciones PRE_ACTION_EXECUTION para darle formato a los datos antes de enviarlos a la actionURL La definición de la función tendrá el siguiente formato: 
//
{
  "functionType": "PRE_ACTION_EXECUTION",
  "functionSource": "..."
}
La función de input debe tener el siguiente formato: 
//
{
  "webhookUrl": "https://actionurl.com/",
  "callbackId": "ap-102670506-56776413549-7-0",
  "origin": {
    "portalId": 102670506,
    "actionDefinitionId": 10646377,
    "actionDefinitionVersion": 1
  },
  "context": {
    "source": "WORKFLOWS",
    "workflowId": 192814114
  },
  "object": {
    "objectId": 904,
    "properties": {
      "email": "[email protected]"
    },
    "objectType": "CONTACT"
  },
  "inputFields": {
    "staticInput": "My Static Input",
    "objectInput": "995",
    "optionsInput": "1"
  }
}
El output de la función debe tener el siguiente formato: 
//
{
  // The webhook URL for HubSpot to call
  "webhookUrl": "https://myapi.com/hubspot",

  // Optional. The request body.
  "body": "{\"widgetName\": \"My new widget\", \"widgetColor\": \"blue\"}",

  // Optional. A map of custom request headers to add.
  "httpHeaders": {
    "My-Custom-Header": "header value"
  },

  // Optional. The Content-Type of the request. Default is application/json.
  "contentType": "application/json",

  // Optional. The Accept type of the request. Default is application/json.
  "accept": "application/json",

  // Optional. The HTTP method with which to make the request.
  // Valid values are GET, POST, PUT, PATCH, and DELETE.
  // Default is POST.
  "httpMethod": "POST"
}

​
Función POST_ACTION_EXECUTION

Después de recibir una respuesta de actionURL, utiliza una función POST_ACTION_EXECUTION para formatear los datos para HubSpot. La definición de la función tendrá el siguiente formato: 
//
{
  "functionType": "POST_ACTION_EXECUTION",
  "functionSource": "..."
}
La función de input debe tener el siguiente formato: 
//
{
  "responseBody": "{\r\n  \"returnValue\":\"Hello World!\"\r\n}"
}
El output de la función debe tener el siguiente formato: 
//
{
  "outputFields": {
    "myOutput": "Some value",
    "hs_execution_state": "SUCCESS"
  }
}

​
Ejecución asíncrona

Ejecuta acciones de workflow personalizadas de forma asíncrona bloqueando y completando posteriormente la acción.

​
Bloquear ejecución de acción

Utiliza acciones personalizadas para bloquear la ejecución del workflow. En lugar de ejecutar la siguiente acción en el workflow después de la acción personalizada después de recibir una respuesta completed (2xx or 4xx status code) desde tu servicio, el workflow dejará de ejecutar (“bloquear”) esa inscripción hasta que el workflow continúe. Al bloquear, puedes especificar un valor para el campo hs_default_expiration, para que la acción personalizada se considere expirada. La ejecución del workflow se reanudará y la acción que sigue a la acción personalizada se ejecutará, aunque no se haya completado la acción. Para bloquear una acción personalizada, la respuesta de ejecución de tu acción debe tener el siguiente formato: 
//
{
  "outputFields": {
    "hs_execution_state": "BLOCK",
    "hs_expiration_duration": "P1WT1H"
  }
}
CampoDescripción
hs_execution_statePara bloquear la ejecución del workflow, esto debe establecerse como BLOCK para la acción personalizada. Este campo es obligatorio.
hs_expiration_durationLa duración debe especificarse en el formato de duración ISO 8601. Si no se proporciona, se utilizará una caducidad por defecto de una semana. Esto es opcional.

​
Completar una ejecución bloqueada

Para completar la ejecución de una acción personalizada bloqueada, utiliza el siguiente endpoint: /callbacks/{callbackId}/complete El cuerpo de la solicitud deberá tener el siguiente formato: 
//
{
  "outputFields": {
    "hs_execution_state": "SUCCESS"
  }
}
CampoDescripción
hs_execution_stateEl estado final de ejecución. Este campo es obligatorio. Los valores válidos para este campo son SUCCESS para indicar que la acción personalizada se completó con éxito, y FAIL_CONTINUE para indicar que hay un problema con la ejecución de la acción personalizada.

​
Agregar mensajes de ejecución personalizados con reglas

Especifica las reglas sobre tu acción para determinar qué mensaje aparece en la página de historial del workflow cuando se ejecuta la acción. Las reglas se ajustarán con los valores de output de tu acción. Estos valores de output se deben proporcionar en el cuerpo de la respuesta de actionURL, en el siguiente formato: 
//
{
  "outputFields": {
    "errorCode": "ALREADY_EXISTS",
    "widgetName": "Test widget"
  }
}
Los mensajes se pueden especificar en la sección de etiquetas de la acción personalizada: 
//
{
  "labels": {
      "executionRules": {
        "alreadyExists": "The widget with name {{ widgetName }} already exists",
        "widgetWrongSize": "Wrong widget size",
        "widgetInvalidSize": "Invalid widget size"
      }
    }
  }
}
Las executionRules se probarán en el orden proporcionado. Si hay varias coincidencias, solo el mensaje de la primera regla que coincide se muestra al usuario. La regla coincide cuando el output de ejecución corresponde a un valor especificado en la regla. Por ejemplo, considera este conjunto de executionRules: 
//
[
  {
    // This matches the key of a label on the action's `labels.LANGUAGE.executionRules` map
    "labelName": "alreadyExists",
    "conditions": {
      "errorCode": "ALREADY_EXISTS"
    }
  },
  {
    "labelName": "widgetWrongSize",
    "conditions": {
      "errorCode": "WIDGET_SIZE",
      "sizeError": ["TOO_SMALL", "TOO_BIG"]
    }
  },
  {
    "labelName": "widgetInvalidSize",
    "conditions": {
      "errorCode": "WIDGET_SIZE"
    }
  }
]
Con lo anterior, se producirían las siguientes coincidencias:
  • {"errorCode": "ALREADY_EXISTS", "widgetName": "Test widget"}: Esto coincidirá con la primera regla, desde errorCode es igual a ALREADY_EXISTS. En este caso, aunque haya una salida widgetName, no se utiliza en la definición de regla, por lo que se permite cualquier valor.
  • {"errorCode": "WIDGET_SIZE", "sizeError": "TOO_SMALL"}: Esto coincidiría con la segunda regla, ya que TOO_SMALL es una de las sizeError coincidentes, y errorCode es WIDGET_SIZE.
  • {"errorCode": "WIDGET_SIZE", "sizeError": "NOT_A_NUMBER"}: Esto coincidiría con la tercera regla, ya que aunque el errorCode es WIDGET_SIZE, el sizeError no coincide con ninguno de los valores especificados por la segunda regla (TOO_SMALL o TOO_BIG).
Este mecanismo de coincidencia te permite especificar errores de reserva, por lo que puedes tener errores específicos para casos de error importantes, pero regresa a mensajes de error genéricos para errores más comunes. Aquí tienes un ejemplo de cómo se mostraría el mensaje personalizado:

​
Probar y publicar la acción personalizada

Después de crear tu nueva acción personalizada, puedes probarla y publicarla.

​
Probar acciones personalizadas antes de publicarlas

Antes de publicar la acción personalizada, puedes probar la ejecución de la acción y las opciones de obtención apuntando la URL a webhook.site. Esto te permite inspeccionar la carga y devolver una respuesta específica. También puedes probar la acción en tu portal de desarrolladores creando un workflow en la herramienta de workflows. Luego, agrega tu nueva acción. Una vez termines las pruebas, se recomienda archivar tus acciones de prueba. Obtén más información sobre archivar las acciones en esta documentación de referencia.

​
Publicar acciones personalizadas

Por opción predeterminada, las acciones personalizadas se crean en un estado no publicado. Las acciones personalizadas que no están publicadas solo son visibles en el portal de desarrolladores asociado con la aplicación de HubSpot correspondiente. Para que la acción personalizada sea visible para los usuarios, actualiza la bandera published en la definición de acción a true. Si una acción no está publicada, los portales que ya han agregado la acción a tu workflow aún podrán editar y ejecutar acciones ya agregadas. Sin embargo, no podrán volver a agregar la acción.

​
Ejemplos de acciones personalizadas

Los fragmentos de código a continuación proporcionan ejemplos de varios casos de uso comunes para acciones personalizadas, como definir un widget o ejecutar una función sin servidor.

​
Primer ejemplo

Este ejemplo se presentan los siguientes campos de entrada, creados para los workflows de contacto y negocio:
  • widgetName: un campo de entrada estático
  • widgetColor: un campo desplegable con opciones
  • widgetOwner: un campo que representa a un propietario de HubSpot.
  • widgetQuantity: un campo derivado de una propiedad (que selecciona el usuario que crea el workflow) en el objeto inscrito.
//
{
  "actionUrl": "https://example.com/hubspot",
  "inputFields": [
    {
      "typeDefinition": {
        "name": "widgetName",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"],
      "isRequired": true
    },
    {
      "typeDefinition": {
        "name": "widgetColor",
        "type": "enumeration",
        "fieldType": "select",
        "options": [
          { "value": "red", "label": "Red" },
          { "value": "blue", "label": "Blue" },
          { "value": "green", "label": "Green" }
        ]
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    },
    {
      "typeDefinition": {
        "name": "widgetOwner",
        "type": "enumeration",
        "referencedObjectType": "OWNER"
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    },
    {
      "typeDefinition": {
        "name": "widgetQuantity",
        "type": "number"
      },
      "supportedValueTypes": ["OBJECT_PROPERTY"]
    }
  ],
  "labels": {
    "en": {
      "actionName": "Create Widget - Example 1",
      "actionDescription": "This action will create a new widget in our system. So cool!",
      "actionCardContent": "Create widget {{widgetName}}",
      "inputFieldLabels": {
        "widgetName": "Widget Name",
        "widgetColor": "Widget Color",
        "widgetOwner": "Widget Owner",
        "widgetQuantity": "Widget Quantity"
      },
      "inputFieldDescriptions": {
        "widgetName": "Enter the full widget name. I support <a href=\"https://hubspot.com\">links</a> too.",
        "widgetColor": "This is the color that will be used to paint the widget."
      }
    }
  },
  "objectTypes": ["CONTACT", "DEAL"]
}

​
Ejemplo #2

La siguiente acción personalizada utiliza una función sin servidor para transformar la carga que se envía a la acción configurada actionUrl. Desde el campo objectTypes no se especifica en la definición de acción personalizada, esta acción estará disponible en todos los tipos de workflows. 
//
{
  "actionUrl": "https://example.com",
  "inputFields": [
    {
      "typeDefinition": {
        "name": "widgetName",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"],
      "isRequired": true
    }
  ],
  "labels": {
    "en": {
      "actionName": "Create Widget - Example 2",
      "actionCardContent": "Create widget {{widgetName}}",
      "inputFieldLabels": {
        "widgetName": "Widget Name"
      }
    }
  },
  "functions": [
    {
      "functionType": "PRE_ACTION_EXECUTION",
      "functionSource": "exports.main = function(event, callback) { return callback(transformRequest(event)); }\nfunction transformRequest(request) { return { webhookUrl: request.webhookUrl, body: JSON.stringify(request.fields), contentType: 'application/x-www-form-urlencoded', accept: 'application/json', httpMethod: 'POST' }; }"
    }
  ]
}

​
Tercer ejemplo

La siguiente acción personalizada tiene dependencias y opciones de campo que se obtienen desde una API externa. Debido a que el tamaño del widget depende del color del widget, el usuario no podrá introducir un valor para el tamaño del widget hasta que elija un color para el widget. El precio del widget también depende de su color, pero está condicionado por el valor que el usuario seleccione para este. El usuario no podrá ingresar un valor para el precio del widget a menos que se seleccione el color rojo. 
//
{
  "actionUrl": "https://example.com/hubspot",
  "inputFields": [
    {
      "typeDefinition": {
        "name": "widgetName",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"],
      "isRequired": true
    },
    {
      "typeDefinition": {
        "name": "widgetColor",
        "type": "enumeration",
        "fieldType": "select",
        "options": [
          { "value": "red", "description": "red", "label": "Red" },
          { "value": "blue", "description": "blue", "label": "Blue" },
          { "value": "green", "description": "green", "label": "Green" }
        ]
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    },
    {
      "typeDefinition": {
        "name": "widgetSize",
        "type": "enumeration",
        "fieldType": "select",
        "optionsUrl": "https://api.example.com/v1/widget-sizes"
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    },
    {
      "typeDefinition": {
        "name": "widgetCost",
        "type": "number",
        "fieldType": "number"
      },
      "supportedValueTypes": ["OBJECT_PROPERTY"]
    }
  ],
  "inputFieldDependencies": [
    {
      "dependencyType": "SINGLE_FIELD",
      "controllingFieldName": "widgetColor",
      "dependentFieldNames": ["widgetSize"]
    },
    {
      "dependencyType": "CONDITIONAL_SINGLE_FIELD",
      "controllingFieldName": "widgetColor",
      "controllingFieldValue": "red",
      "dependentFieldNames": ["widgetCost"]
    }
  ],
  "labels": {
    "en": {
      "actionName": "Create Widget - Example 3",
      "actionCardContent": "Create widget {{widgetName}}",
      "inputFieldLabels": {
        "widgetName": "Widget Name",
        "widgetColor": "Widget Color",
        "widgetSize": "Widget Size",
        "widgetCost": "Widget Cost"
      }
    }
  },
  "objectTypes": ["CONTACT", "DEAL"],
  "functions": [
    {
      "functionType": "PRE_FETCH_OPTIONS",
      "id": "widgetSize",
      "functionSource": "exports.main = function(event, callback) { return callback(transformRequest(event)); }\nfunction transformRequest(request) { return { webhookUrl: request.webhookUrl + '?color=' + request.fields.widgetColor.value, body: JSON.stringify(request.fields), httpMethod: 'GET' }; }"
    }
  ]
}
Last modified on December 10, 2025