Webhooks
La API de Webhooks permite suscribirse a eventos que ocurren en una cuenta de HubSpot con la integración instalada. En lugar de hacer una llamada de API cuando ocurre un evento en una cuenta conectada, HubSpot puede enviar una solicitud HTTP a un punto de terminación que configures. Puedes configurar eventos suscritos en la configuración de tu aplicación o usar los puntos de terminación que se detallan a continuación. Los webhooks pueden ser más escalables que la interrogación frecuente por cambios, especialmente para aplicaciones con una gran base instalada.
El uso de la API de Webhooks requiere de lo siguiente:
- Debes configurar una aplicación de HubSpot para usar webhooks mediante la suscripción a los eventos sobre los que deseas recibir notificaciones y la especificación de una URL para enviar esas notificaciones. Consulta la documentación de requisitos previos para obtener más detalles sobre cómo crear una aplicación.
- Debes implementar un punto de terminación de HubSpot disponible públicamente y seguro (HTTPS) para esa URL que pueda manejar las cargas útiles del webhook especificadas en esta documentación.
Los webhooks se configuran para una aplicación de HubSpot, no para cuentas individuales. Cualquier cuenta que instale tu aplicación a través del flujo de OAuth se suscribirá a las suscripciones a webhook de la aplicación.
Puedes suscribirte a eventos de objetos de CRM, que incluyen contactos, empresas, negocios, tickets, productos y elementos de línea, así como eventos de conversación.
Please note: to subscribe to conversations webhooks, you need access to the conversations inbox and messages APIs, which is currently in beta.
Para usar webhooks para suscribirte a eventos de CRM, tu aplicación deberá estar configurada para requerir el alcance de crm.objects.contacts.read. Tu aplicación deberá estar configurada para requerir el alcance de conversaciones.read para suscribirse a eventos de conversaciones.
Debes configurar estos alcances antes de crear una suscripción a webhook. Consulta la documentación de OAuth para obtener más detalles sobre los alcances y la configuración de la URL de autorización para tu aplicación.
Si tu aplicación ya está usando webhooks, no podrás eliminar el alcance de crm.objects.contacts.read o conversations.read hasta que elimines todas las suscripciones de webhook de tu aplicación.
Antes de configurar tus suscripciones de webhook, debes especificar una URL a la que se enviarán esas notificaciones. También puedes ajustar el límite de supresión de eventos, que es el número de solicitudes concurrentes que tu punto de conexión puede manejar.
Este límite de supresión es un límite de concurrencia, por lo que tan pronto como haya una respuesta a una solicitud, el total de solicitudes activas se reducirá en una y se puede enviar otra solicitud. Por ejemplo, si tienes un límite de 1 solicitud por 10 segundos, si se envía 1 solicitud, HubSpot esperará una respuesta o durante 10 segundos antes de enviar otra solicitud, lo que ocurra primero.
Establecer este límite de tasa nos ayuda a enviar notificaciones lo más rápido posible sin poner demasiada carga en tu API.
- Si configuras este límite demasiado bajo, es posible que se agote el tiempo de espera si se envían demasiadas notificaciones a tu API y el límite se satura por más de unos cuantos segundos. Esto ocasionará demoras en la notificación.
- Si configuras este límite demasiado alto, podrías saturar los recursos disponibles para tu punto de terminación, lo que podría generar respuestas lentas, retrasos en las notificaciones o que tu punto de terminación deje de responder.
Puedes administrar tu URL y el límite de supresión a través de la página de configuración de tu aplicación en tu cuenta de desarrollador
- En tu cuenta de desarrollador, navega al panel de tu aplicación.
- Haz clic en el nombre de la aplicación para la que deseas configurar los webhooks.
- En el menú de la barra lateral izquierda, ve a Webhooks.
- En el campo URL de destino, escribe la URL a la que HubSpot realizará una solicitud POST cuando se desencadenen eventos.
- Utiliza la configuración de Supresión de eventos para ajustar el número máximo de eventos que HubSpot intentará enviar.
- Haz clic en Guardar.
Puedes usar los siguientes puntos de terminación y tu clave de API de desarrollador para configurar de forma programática la configuración de webhook para una aplicación.
Para ver cualquier configuración de webhook configurada actualmente para una aplicación, realiza una solicitud GET a webhooks/v3/{appId}/settings.
Deberás incluir el ID de la aplicación en la solicitud, que puedes encontrar debajo del nombre de la aplicación en tu panel de control de Aplicaciones o en la pestaña Autenticación en la configuración de tu aplicación.
El objeto de configuración contiene los siguientes campos:
| Campo | Description |
|---|---|
webhookUrl
| La URL a la que HubSpot enviará notificaciones de webhook. Esta URL se debe notificar por HTTPS. |
maxConcurrentRequests
| El límite de concurrencia para la URL del webhook. Este valor debe ser un número mayor que cinco. |
Para hacer ediciones a esta configuración, haz una solicitud PUT a webhooks/v3/{appId}/settings e incluye los siguientes campos en el cuerpo de la solicitud:
| Campo | Description |
|---|---|
targetUrl
| La URL disponible públicamente para que HubSpot llame donde se entregarán las cargas útiles de eventos. |
throttling
| Configurar los detalles de la supresión de webhooks en este objeto. El objeto de supresión incluye los campos |
period
| Escala de tiempo para esta configuración. Puede ser |
maxConcurrentRequests
| El número máximo de solicitudes HTTP que HubSpot intentará hacer a tu aplicación en un plazo determinado por |
Por ejemplo, el cuerpo de tu solicitud puede tener un aspecto similar al siguiente:
Una vez que hayas establecido las configuraciones de tu URL de webhook y del límite de supresión de eventos, deberás crear una o más suscripciones. Las suscripciones a webhooks le indican a HubSpot los eventos que te gustaría recibir a una aplicación en particular.
Las suscripciones se aplican a todos los clientes oMS han instalado tu integración. Esto significa que solo debes especificar las suscripciones que necesitas una vez. Una vez que hayas activado una suscripción para una aplicación, comenzarás automáticamente a recibir webhooks para todos los clientes que hayan instalado tu aplicación y tu integración comenzará a recibir activadores de webhook desde cualquier cliente nuevo.
Los siguientes tipos de suscripción son compatibles y se pueden usar como valor para el campo eventType al crear suscripciones a través de API:
| Tipo de suscripción | Alcance requerido | Descripción |
|---|---|---|
contact.creation |
crm.objects.contacts.read |
Recibir una notificación si se crea algún contacto en la cuenta de un cliente. |
contact.deletion |
Recibe una notificación si se elimina algún contacto en la cuenta de un cliente. | |
contact.merge |
Recibe una notificación si se combinó un contacto con otro. | |
contact.associationChange |
Recibe una notificación si un contacto tiene una asociación agregada o eliminada entre él y otro objeto de webhook compatible (contacto, empresa, negocio, ticket, elemento de línea o producto). | |
contact.restore |
Recibe una notificación si se restaura un contacto después de la eliminación. | |
contact.privacyDeletion |
Recibie una notificación si se elimina un contacto por motivos de cumplimiento de la privacidad. | |
contact.propertyChange |
Recibe una notificación si se cambia una propiedad específica para cualquier contacto en una cuenta. | |
company.creation |
crm.objects.companies.read |
Recibe una notificación si se crea alguna empresa en la cuenta de un cliente. |
company.deletion |
Recibe una notificación si se elimina alguna empresa en la cuenta de un cliente. | |
company.propertyChange |
Recibe una notificación si se cambia una propiedad específica para cualquier empresa en la cuenta de un cliente. | |
company.associationChange |
Recibe una notificación si una empresa tiene una asociación agregada o eliminada entre ella y otro objeto de webhook compatible (contacto, empresa, negocio, ticket, elemento de línea o producto). | |
company.restore |
Recibe una notificación si una empresa se restaura después de la eliminación. | |
company.merge |
Recibir una notificación si una empresa se fusionó con otra. | |
deal.creation |
crm.objects.deals.read |
Recibe una notificación si se crea un negocio en la cuenta de un cliente. |
deal.deletion |
Recibe una notificación si se elimina algún negocio en la cuenta de un cliente. | |
deal.associationChange |
Recibir una notificación si un negocio tiene una asociación agregada o eliminada entre él y otro objeto de webhook compatible (contacto, empresa, negocio, ticket, elemento de línea o producto). | |
deal.restore |
Recibe una notificación si se restaura un negocio después de la eliminación. | |
deal.merge |
Recibe una notificación si un negocio se fusiona con otro. | |
deal.propertyChange |
Recibe una notificación si se cambia una propiedad específica para cualquier negocio en la cuenta de un cliente. | |
ticket.creation |
tickets |
Recibe una notificación si se crea un ticket en la cuenta de un cliente. |
ticket.deletion |
Recibe una notificación si se elimina algún ticket en la cuenta de un cliente. | |
ticket.propertyChange |
Recibir una notificación si se cambia una propiedad específica para cualquier ticket en la cuenta de un cliente. | |
ticket.associationChange |
Recibe una notificación si un ticket tiene una asociación agregada o eliminada entre él y otro objeto de webhook compatible (contacto, empresa, negocio, ticket, elemento de línea o producto). | |
ticket.restore |
Recibe una notificación si se restaura un ticket después de su eliminación. | |
ticket.merge |
Recibe una notificación si un ticket se combinó con otro. | |
product.creation |
e-commerce |
Recibe una notificación si se crea algún producto en la cuenta de un cliente. |
product.deletion |
Recibe una notificación si se elimina algún producto en la cuenta de un cliente. | |
product.restore |
Recibe una notificación si un producto se restaura después de su eliminación. | |
product.merge |
Recibe una notificación si un producto se combinó con otro. | |
product.propertyChange |
Recibe una notificación si se cambia un producto específico para cualquier producto en la cuenta de un cliente. | |
line_item.creation |
Recibe una notificación si se crea algún elemento de línea en la cuenta de un cliente. | |
line_item.deletion |
Recibe una notificación si se elimina algún elemento de línea en la cuenta de un cliente. |
|
line_item.associationChange |
Recibe una notificación si un elemento de línea tiene una asociación agregada o eliminada entre él y otro objeto de webhook compatible (contacto, empresa, negocio, ticket, elemento de línea o producto). | |
line_item.restore |
Recibe una notificación si un elemento de línea se restaura después de la eliminación. | |
line_item.merge |
Recibe una notificación si un elemento de línea se combinó con otro. | |
line_item.propertyChange |
Recibe una notificación si se cambia una propiedad específica para cualquier elemento de línea en la cuenta de un cliente. |
Los siguientes tipos de suscripción de conversaciones están disponibles para que te suscribas si estás usando la bandeja de entrada de conversaciones y la API de mensajes, que actualmente está en versión beta:
| Tipo de suscripción | Alcance | Descripción |
|---|---|---|
conversation.creation |
conversations.read |
Recibe notificaciones si se crea un nuevo hilo en una cuenta. |
conversation.deletion |
Recibe una notificación si un hilo se archiva o se elimina temporalmente en una cuenta. | |
conversation.privacyDeletion |
Recibe una notificación si un hilo se elimina permanentemente en una cuenta. | |
conversation.propertyChange |
Recibe una notificación si se ha cambiado una propiedad en un hilo. | |
conversation.newMessage |
Recibe una notificación si se ha recibido un nuevo mensaje en un hilo. |
Para las suscripciones de cambio de propiedad, deberás especificar la propiedad de la que deseas recibir notificaciones. Puedes especificar varias suscripciones de cambios de propiedad. Si la cuenta de un cliente no tiene la propiedad que especificas en una suscripción, no recibirás ningún webhooks de ese cliente para esa propiedad.
Algunas propiedades no están disponibles para suscripciones de cambio de propiedad de CRM. Estas propiedades son:
num_unique_conversion_eventshs_lastmodifieddate
Si estás usando los mensajes de conversación y la API de la bandeja de entrada, que se encuentra actualmente en versión beta, las siguientes propiedades están disponibles:
assignedTo: el hilo de conversación se ha reasignado o no asignado. Si se reasignó el hilo, el valorpropertyValueserá un ID de actor en la carga útil de webhooks; si no se asigna, estará vacío.status: el estado del hilo de conversación ha cambiado. En la carga útil de webhooks, el valorpropertyValueestaráOPENoCLOSED.isArchived: se ha restaurado el hilo de conversación. El valorpropertyValueen la carga útil de webhooks siempre seráFALSE.
Puedes crear suscripciones de webhook en tu cuenta de desarrollador de HubSpot.
- En tu cuenta de desarrollador de HubSpot, navega al panel de Aplicaciones.
- Haz clic en el nombre de una aplicación.
- En el menú de la barra lateral izquierda, ve a Webhooks.
- Haz clic en Crear suscripción.
- En el panel derecho, haz clic en el menú desplegable ¿Qué tipos de objetos? y selecciona los objetos para los que deseas crear una suscripción.
- Haz clic en el menú desplegable ¿Escuchar cuáles eventos? y selecciona los tipos de eventos.
- Si estás creando una suscripción para eventos de cambio de propiedad, haz clic en el menú desplegable ¿Qué propiedades? y selecciona las propiedades que quieres escuchar.
- Haz clic en Suscribirse.
La suscripción aparecerá en la configuración de tus webhooks. Las nuevas suscripciones se crean en un estado en pausa, por lo que deberás activar la suscripción para que se envíen webhooks:
- En la sección Suscripciones de eventos, coloca el cursor sobre el tipo de objeto y haz clic en Ver suscripciones.
- Selecciona la casilla de comprobación junto al evento y, a continuación, en el encabezado de la tabla, haz clic en Activar.
Puedes crear suscripciones mediante programación usando los siguientes puntos de terminación. Deberás usar tu clave de API de desarrollador al realizar solicitudes a estos puntos de terminación.
Un objeto de suscripción puede incluir los siguientes campos:
| Campo | Description |
|---|---|
id
| Un número que representa el ID único de una suscripción. |
createdAt
| El tiempo en milisegundos en que se creó esta suscripción. |
createdBy
| El ID de usuario asociado con el usuario que creó la suscripción. |
active
| Esto indica si la suscripción está activada o no y si activa notificaciones de forma activa. El valor puede ser |
eventType
| El tipo de suscripción. La tabla al comienzo de esta sección incluye los tipos de suscripción disponibles. |
propertyName
| El nombre de la propiedad en la que la suscripción escuchará los cambios. Esto solo es necesario para los tipos de suscripción de cambio de propiedad. |
Para recuperar la lista de suscripciones, realiza una solicitud GET a webhooks/v3/{appId}/subscriptions.
La respuesta será una matriz de objetos que representan tus suscripciones. Cada objeto incluirá información sobre la suscripción, como el ID, la fecha de creación, el tipo y si está habilitado actualmente. Así es como se vería un ejemplo de respuesta:
Para crear una nueva suscripción, haz una solicitud POST a webhooks/v3/{appId}/subscriptions.
En el cuerpo de la solicitud, puedes incluir los siguientes campos:
| Campo | Description |
|---|---|
eventType
| El tipo de suscripción. |
propertyName
| El nombre de la propiedad en la que la suscripción escuchará los cambios. Esto solo es necesario para los tipos de suscripción de cambio de propiedad. |
active
| Esto indica si la suscripción está activada o no y si activa notificaciones de forma activa. El valor puede ser |
No necesitas incluir id, createdAt o createdBy, ya que esos campos se establecen automáticamente.
Por ejemplo, el cuerpo de tu solicitud puede tener un aspecto similar al siguiente:
El eventType debe ser un tipo de suscripción válido según se define en la sección anterior y el propertyName debe ser un nombre de propiedad válido. Si un cliente no tiene una propiedad definida que coincida con este valor, esta suscripción no generará notificaciones.
Para activar o pausar una suscripción, haz una solicitud PUT a webhooks/v3/{appId}/subscriptions/{subscriptionId}.
En el cuerpo de la solicitud, incluye lo siguiente:
| Campo | Description |
|---|---|
active
| Esto indica si la suscripción está activada o no y si activa notificaciones de forma activa. El valor puede ser |
Para eliminar una suscripción, haz una solicitud DELETE a webhooks/v3/{appId}/subscriptions/{subscriptionId}.
El punto de terminación de la URL de destino que especifiques en la configuración de webhooks de tu aplicación recibirá solicitudes POST que contienen datos con formato JSON de HubSpot.
Para asegurarte de que las solicitudes que recibes en tu punto de terminación de webhook provengan de HubSpot, HubSpot rellena un encabezado de X-HubSpot-Signature con un hash SHA-256 creado con el secreto del cliente de tu aplicación combinado con los detalles de la solicitud. Más información sobre cómo validar firmas de solicitudes.
Utiliza las tablas a continuación para ver detalles sobre los campos que pueden estar contenidos en la carga útil.
| Campo | Description |
|---|---|
objectId
| El ID del objeto que fue creado, cambiado o eliminado. Para contactos, este es el ID de contacto; para empresas, el ID de empresa; para negocios, el ID de negocio; y para conversaciones el ID de hilo. |
propertyName
| Esto solo se envía para las suscripciones de cambio de propiedad y es el nombre de la propiedad que se cambió. |
propertyValue
| Esto solo se envía para suscripciones de cambio de propiedad y representa el nuevo valor establecido para la propiedad que desencadenó la notificación. |
changeSource
| La fuente del cambio. Puede ser cualquiera de las fuentes de cambios que aparecen en los historiales de las propiedades de contactos. |
eventId
| El ID único del evento que desencadenó esta notificación. No se garantiza que este valor sea único. |
subscriptionId
| El ID de la suscripción que desencadenó una notificación sobre el evento. |
portalId
| El ID de cuenta de HubSpot del cliente donde ocurrió el evento. |
appId
| El ID de tu aplicación. Esto se usa en caso de que tengas varias aplicaciones que apunten a la misma URL de webhook. |
occurredAt
| Cuándo ocurrió este evento como una marca de tiempo de milisegundos. |
eventType
| El tipo de evento para el que es esta notificación. Revisa la lista de tipos de suscripción admitidos en la sección de suscripción de webhooks anterior. |
attemptNumber
| A partir de 0, el número de intentos es para notificar a su servicio de este evento. Si se vence el tiempo de espera de tu servicio o emite un mensaje de error, tal como se describe en la sección Reintentos a continuación, HubSpot intentará enviar la notificación de nuevo. |
messageId
| Esto solo se envía cuando un webhook está escuchando nuevos mensajes en un hilo. Es el ID del nuevo mensaje. |
messageType
| Esto solo se envía cuando un webhook está escuchando nuevos mensajes en un hilo. Representa el tipo de mensaje que estás enviando. Este valor puede ser |
| Campo | Description |
|---|---|
primaryObjectId
| El ID del ganador de la combinación, que es el registro que permanece después de la combinación. En la interfaz de usuario de fusión de HubSpot, este es el registro de la derecha. |
mergedObjectIds
| Una matriz de identificadores que representan los registros que se fusionan en el ganador de la fusión. En la interfaz de usuario de fusión de HubSpot, este es el registro a la izquierda. |
newObjectId
| El ID del registro que se crea como resultado de la combinación. Esto es independiente de |
numberOfPropertiesMoved
| Un entero que representa cuántas propiedades se transfirieron durante la combinación. |
| Campo | Description |
|---|---|
associationType
| El tipo de asociación, que será una de las siguientes:
|
fromObjectId
| El ID del registro desde el que se realizó el cambio de asociación. |
toObjectId
| El ID del registro secundario en el evento de asociación. |
associationRemoved
| Un booleano que representa lo siguiente:
|
isPrimaryAssociation
| Un booleano que representa lo siguiente:
Nota: la creación de una instancia de asociación primaria entre dos registros de objetos hará que también se cree la asociación no primaria correspondiente. Esto puede generar dos mensajes de webhook. |
Como se muestra anteriormente, debes esperar recibir una matriz de objetos en una sola solicitud. El tamaño del lote puede variar, pero tendrá menos de 100 notificaciones. HubSpot enviará varias notificaciones solamente cuando hayan ocurrido muchos eventos dentro de un período corto de tiempo. Por ejemplo, si te has suscrito a nuevos contactos y un cliente importa una gran cantidad de contactos, HubSpot te enviará las notificaciones de estos contactos importados en lotes y no una por solicitud.
HubSpot no garantiza que recibas estas notificaciones en el orden en que ocurrieron. Usa la propiedad occurredAt para cada notificación para determinar cuándo ocurrió el evento que desencadenó la notificación.
Además, HubSpot no garantiza que solo recibas una notificación para un evento. Aunque esto debería ser poco común, es posible que HubSpot te envíe la misma notificación varias veces.
Los usuarios de HubSpot pueden eliminar permanentemente un registro de contacto para cumplir con las leyes de privacidad. Más información sobre cómo realizar una eliminación conforme al RGPD.
Puedes suscribirte al tipo de suscripción contact.privacyDeletion para recibir notificaciones de webhook cuando un usuario realice una eliminación de contactos conforme con la privacidad.
Las notificaciones de eliminación conforme con la privacidad tienen un comportamiento especial
- Un evento de eliminación conforme con la privacidad también desencadenará el evento de eliminación de contacto, por lo que recibirás dos notificaciones si estás suscrito a ambos eventos.
- Estas notificaciones no se enviarán necesariamente en ningún orden en particular o en el mismo lote de mensajes. Deberás usar el objectId para que coincida con los mensajes separados.
Para asegurarte de que las solicitudes que recibes en tu punto de terminación de webhook provienen de HubSpot, HubSpot llena un encabezado de X-HubSpot-Signature con un hash SHA-256 de la concatenación del secreto de aplicación para tu aplicación y el cuerpo de la solicitud que estamos enviando.
Para verificar esta firma, concatena el secreto de la aplicación de tu aplicación y el cuerpo de solicitud no interpretado de la solicitud que estás manejando y obtén un hash SHA-256 del resultado. Compara el hash resultante con el valor de X-HubSpot-Signature. Si estos valores coinciden, se confirma que esta solicitud es proveniente de HubSpot. O bien, la solicitud provino de otra persona que conoce el secreto de tu aplicación. Es importante mantener este valor en secreto.
Si estos valores no coinciden, es posible que esta solicitud haya sido manipulada en tránsito o que alguien esté falsificando notificaciones de webhook a tu punto de terminación.
Más información sobre la validación de solicitudes de firmas.
Si tu servicio tiene problemas para manejar las notificaciones en cualquier momento, HubSpot intentará volver a enviar notificaciones fallidas hasta 10 Veces.
HubSpot lo intentará nuevamente en los casos siguientes:
- Falló la conexión: HubSpot no puede abrir una conexión http a la URL de webhook proporcionada
- Tiempo de espera: tu servicio demora más de 5 segundos en enviar una respuesta a un lote de notificaciones
- Códigos de error:tu servicio responde con cualquier código de estado HTTP (4xx o 5xx).
Las notificaciones se volverán a intentar hasta 10 Veces. Estos reintentos se distribuirán durante las próximas 24 horas, con distintos retrasos entre las solicitudes. Las notificaciones individuales serán enviadas de manera aleatoria, para evitar que un gran número de errores concurrentes se vuelva a intentar en el mismo momento.
Gracias por tus comentarios, son muy importantes para nosotros.