Ignorar e ir ao conteúdo principal

A API de Webhooks permite assinar eventos que acontecem em uma conta da HubSpot com sua integração instalada. Em vez de fazer uma chamada de API quando um evento acontece em uma conta conectada, o HubSpot pode enviar uma solicitação HTTP para um ponto de extremidade que você configurar. Você pode configurar eventos assinados nas configurações de seu aplicativo ou usando os pontos de extremidade detalhados abaixo. Os Webhooks podem ser uma alternativa mais escalável do que verificar alterações com frequência, especialmente para aplicativos com uma base de instalação grande.

O uso da API dos Webhooks requer o seguinte:

  • Você deve configurar um aplicativo da HubSpot para usar webhooks, inscrevendo-se nos eventos sobre os quais deseja ser notificado e especificando um URL para envio dessas notificações. Consulte a documentação dos pré-requisitos para obter mais informações sobre como criar um aplicativo.
  • Você deve implantar um ponto de extremidade seguro (HTTPS) e disponível publicamente para esse URL que seja capaz de lidar com as cargas do webhook especificadas nesta documentação.

Os webhooks estão configurados para um aplicativo da HubSpot, e não para contas individuais. Todas as contas que instalarem seu aplicativo passando pelo fluxo de OAuth serão inscritas nas respectivas assinaturas do webhook.

Você pode se inscrever em eventos de objeto do CRM, que incluem contatos, empresas, negócios, tickets, produtos e itens de linha, bem como em eventos de conversas.

Para usar webhooks para assinar os eventos do CRM, o aplicativo precisará ser configurado para exigir o escopo associado que corresponde ao tipo de objeto do CRM no qual você deseja se inscrever. Por exemplo, se quiser se inscrever em eventos de contatos, você terá que solicitar o escopo crm.objects.contacts.read.

  • Ao criar assinaturas na interface de configurações do seu aplicativo público, você será solicitado a adicionar o escopo necessário no painel Criar novas assinaturas do webhook antes de terminar de criar a assinatura.
  • Se você estiver criando uma assinatura ao fazer uma solicitação POST para o ponto de extremidade /webhooks/v3/{appId}/subscriptions, a resposta incluirá um erro contendo o nome do escopo que você precisará definir nas configurações da interface do usuário do seu aplicativo público.
  • Se o seu aplicativo já estiver usando webhooks, você não poderá remover nenhum escopo exigido pelas assinaturas de webhooks ativas sem primeiro pausar e remover as assinaturas.
  • Você pode revisar os escopos necessários para cada tipo de assinatura de webhook na tabela abaixo.

Revise a documentação de OAuth para obter mais detalhes sobre os escopos e configurar o URL de autorização para o seu aplicativo.

Antes de configurar suas assinaturas de Webhook, você precisa especificar um URL para o qual essas notificações serão enviadas. Siga as instruções nas secções abaixo para saber como configurar totalmente as assinaturas do seu aplicativo.

Você pode gerenciar a URL e o limite de acúmulo de eventos na página de configuração do aplicativo em sua conta de desenvolvedor:

  • Na sua conta de desenvolvedor, acesse o painel Aplicativo.

  • Clique no nome do aplicativo para o qual deseja configurar os webhooks.

    app_id_list

  • No menu da barra lateral esquerda, acesse Webhooks.

  • No campo URL de destino, insira a URL para a qual o HubSpot fará uma solicitação POST quando os eventos forem disparados.

  • Use a configuração Acúmulo de eventos para ajustar o número máximo de eventos que o HubSpot tentará enviar.

webhook_settings

  • Clique em Salvar.

Você pode usar os seguintes pontos de extremidade e sua chave de API de desenvolvedor para configurar programaticamente as configurações do webhook para um aplicativo.

Para exibir as configurações de webhooks definidas para um aplicativo, faça uma solicitação GET para webhooks/v3/{appId}/settings.

Você precisará incluir o ID do aplicativo na solicitação, que pode ser encontrado abaixo do nome do aplicativo no painel Aplicativos ou na guia Autenticação nas configurações do aplicativo.

O objeto de configuração contém os seguintes campos:

CampoDescription
webhookUrlA URL para a qual o HubSpot enviará notificações de webhook. A URL deve ser atendida por HTTPS.
maxConcurrentRequestsO limite de concorrência para a URL do webhook. Este valor deve ser um número maior que cinco.

Para editar essas configurações, faça uma solicitação PUT para webhooks/v3/{appId}/settings e inclua os seguintes campos no corpo da solicitação:

CampoDescription
targetUrlA URL disponível publicamente para que o HubSpot indique onde as payloads do evento serão entregues.
acúmuloConfigure os detalhes de acúmulo do webhook neste objeto. O objeto de acúmulo inclui os campos period e maxConcurrentRequests.
períodoEscala de tempo para esta configuração. Pode ser SECONDLY (por segundo) ou ROLLING_MINUTE (por minuto).
maxConcurrentRequestsO número máximo de solicitações HTTP que o HubSpot tentará fazer para o seu aplicativo em um período de tempo determinado por period.

Por exemplo, o corpo da solicitação pode ser parecido com o seguinte:

Depois de definir a URL do Webhook e o limite de acúmulo de eventos, será necessário criar uma ou mais assinaturas. As assinaturas do Webhook informam ao HubSpot quais eventos seu aplicativo específico gostaria de receber.

As assinaturas se aplicam a todos os clientes que instalaram sua integração. Isso significa que basta você especificar uma vez as assinaturas de que precisa. Depois que uma assinatura for ativada para um aplicativo, ele começará a receber webhooks automaticamente de todos os clientes que instalaram seu aplicativo, e sua integração começará a receber gatilhos de webhook de qualquer novo cliente.

Para todas as assinaturas de webhook associationChange, o webhook disparará dois eventos para ambos os lados da associação.

  • Ao associar dois contatos, uma assinatura de contact.associationChange disparará dois eventos, representando contact 1 to contact 2 e contact 2 to contact 1.
  • Ao associar uma empresa, se você tiver duas assinaturas de webhook, contact.associationChange e company.associationChange, receberá dois eventos. Estes representarão contact 1 to company 1 e company 1 to contact 1.

Os seguintes tipos de assinatura são suportados e podem ser usados como valor para o campo eventType ao criar assinaturas por meio da API:

Tipo de assinaturaEscopo obrigatórioDescrição
contact.creationcrm.objects.contacts.readReceba uma notificação se um contato for criado na conta de um cliente.
contact.deletionReceba uma notificação se um contato for excluído na conta de um cliente.
contact.mergeReceba uma notificação se um contato for mesclado com outro.
contact.associationChangeReceba uma notificação se um contato tiver uma associação adicionada ou removida entre ele e outro objeto de webhook suportado (contato, empresa, negócio, ticket, item de linha ou produto).
contact.restoreReceba uma notificação se um contato for restaurado da exclusão.
contact.privacyDeletionReceba uma notificação se um contato for excluído por motivos de conformidade com a privacidade.
contact.propertyChangeReceba uma notificação se uma propriedade específica for alterada para um contato em uma conta.
company.creationcrm.objects.companies.readReceba uma notificação se uma empresa for criada na conta de um cliente.
company.deletionReceba uma notificação se uma empresa for excluída na conta de um cliente.
company.propertyChangeReceba uma notificação se uma propriedade específica for alterada para uma empresa na conta de um cliente.
company.associationChangeReceba uma notificação se uma empresa tiver uma associação adicionada ou removida entre ela e outro objeto de webhook suportado (contato, empresa, negócio, ticket, item de linha ou produto).
company.restoreReceba uma notificação se uma empresa for restaurada da exclusão.
company.mergeReceba uma notificação se uma empresa for mesclada com outra.
deal.creationcrm.objects.deals.readReceba uma notificação se um negócio for criado na conta de um cliente.
deal.deletionReceba uma notificação se um negócio for excluído na conta de um cliente.
deal.associationChangeReceba uma notificação se um negócio tiver uma associação adicionada ou removida entre ele e outro objeto de webhook suportado (contato, empresa, negócio, ticket, item de linha ou produto).
deal.restoreReceba uma notificação se um negócio for restaurado da exclusão.
deal.mergeReceba uma notificação se um negócio for mesclado com outro.
deal.propertyChangeReceba uma notificação se uma propriedade específica for alterada para um negócio na conta de um cliente.
ticket.creationticketsReceba uma notificação se um ticket for criado na conta de um cliente.
ticket.deletionReceba uma notificação se um ticket for excluído na conta de um cliente.
ticket.propertyChangeReceba uma notificação se uma propriedade específica for alterada para um ticket na conta de um cliente.
ticket.associationChangeReceba uma notificação se um ticket tiver uma associação adicionada ou removida entre ele e outro objeto de webhook suportado (contato, empresa, negócio, ticket, item de linha ou produto).
ticket.restoreReceba uma notificação se um tíquete for restaurado da exclusão.
ticket.mergeReceba uma notificação se um ticket for mesclado com outro.
product.creatione-commerceReceba uma notificação se um produto for criado na conta de um cliente.
product.deletionReceba uma notificação se um produto for excluído na conta de um cliente.
product.restoreReceba uma notificação se um produto for restaurado da exclusão.
product.mergeReceba uma notificação se um produto for mesclado com outro.
product.propertyChangeReceba uma notificação se um produto específico for alterado para um produto na conta de um cliente.
line_item.creationReceba uma notificação se um item de linha for criado na conta de um cliente.
line_item.deletionReceba uma notificação se um item de linha for excluído na conta de um cliente.
line_item.associationChangeReceba uma notificação se um item de linha tiver uma associação adicionada ou removida entre ele e outro objeto de webhook suportado (contato, empresa, negócio, ticket, item de linha ou produto).
line_item.restoreReceba uma notificação se um item de linha for restaurado da exclusão.
line_item.mergeReceba uma notificação se um item de linha for mesclado com outro.
line_item.propertyChangeReceba uma notificação se uma propriedade específica for alterada para um item de linha na conta de um cliente.

Os seguintes tipos de assinatura de conversas estão disponíveis para você assinar se estiver usando aAPI de mensagens e caixa de entrada de conversas, que está atualmente em versão beta:

Tipo de assinaturaScopeDescrição
conversation.creationconversations.readReceba uma notificação se um novo thread for criado em uma conta.
conversation.deletionReceba uma notificação se um thread for arquivado ou excluído de forma reversível em uma conta.
conversation.privacyDeletionReceba uma notificação se um thread for excluído permanentemente em uma conta.
conversation.propertyChangeReceba uma notificação se uma propriedade em um thread for alterada.
conversation.newMessageReceba uma notificação se uma nova mensagem for recebida em um thread.

No caso de assinaturas de alteração de propriedade, você precisará especificar sobre quais propriedades deseja ser notificado. É possível especificar várias assinaturas de alteração de propriedade. Se a conta de um cliente não tiver a propriedade especificada em uma assinatura, você não receberá webhooks desse cliente para essa propriedade.

Algumas propriedades não estão disponíveis para assinaturas de alteração de propriedade do CRM. São elas:

  • num_unique_conversion_events
  • hs_lastmodifieddate

Se você estiver usando a API de caixa de entrada e mensagens de conversas, que está atualmente em versão beta, as seguintes propriedades estarão disponíveis:

  • assignedTo: o thread da conversa foi reatribuído ou teve sua atribuição cancelada. Se o thread foi reatribuído, propertyValue será um ID de ator na payload dos webhooks; se teve sua atribuição cancelada, a propriedade estará vazia.
  • status: o status do thread de conversas foi alterado. Na carga útil dos webhooks, propertyValue será OPEN ou CLOSED.
  • isArchived: o thread da conversa foi restaurado. O propertyValue na payload dos webhooks sempre será FALSE.

Você pode criar assinaturas de webhook em sua conta de desenvolvedor da HubSpot.

  • Na sua conta de desenvolvedor da HubSpot, acesse o painel Aplicativos.
  • Clique no nome de um aplicativo.
  • No menu da barra lateral esquerda, acesse Webhooks.
  • Clique em Criar assinatura.
  • No painel direito, clique no menu suspenso Quais tipos de objeto? e selecione os objetos para os quais você deseja criar uma assinatura.
  • Clique no menu suspenso Monitorar quais eventos? e selecione os tipos de eventos.

create-contact-create-subscription

  • Se você estiver criando uma assinatura para eventos de alteração de propriedade, clique no menu suspenso Quais propriedades? e selecione as propriedades que devem ser monitoradas.

  • Clique em Assinar.

A assinatura aparecerá nas configurações de webhooks. Novas assinaturas são criadas em um estado pausado; você precisará ativar a assinatura para que os webhooks sejam enviados:

  • Na seção Assinaturas de eventos, passe o mouse sobre o tipo de objeto e clique em Exibir assinaturas.
  • Marque a caixa de seleção ao lado do evento e, no cabeçalho da tabela, clique em Ativar.

activate-subscription

Você pode criar assinaturas de forma programática usando os pontos de extremidade a seguir. Você precisará usar sua chave de API de desenvolvedor ao fazer solicitações para esses pontos de extremidade.

O objeto de assinatura pode incluir os seguintes campos:

CampoDescription
idUm número que representa o ID exclusivo de uma assinatura.
createdAtA hora em milissegundos em que essa assinatura foi criada.
createdByO ID associado ao usuário que criou a assinatura.
inteligenteIndica se a assinatura está ativada e disparando notificações de forma ativa. O valor pode ser true ou false.
eventTypeO tipo de assinatura. A tabela no início desta seção inclui os tipos de assinatura disponíveis.
propertyNameO nome da propriedade em que a assinatura monitorará as alterações. Isso é necessário apenas para tipos de assinatura de alteração de propriedade.

Para recuperar a lista de assinaturas, faça uma solicitação GET para webhooks/v3/{appId}/subscriptions.

A resposta será um conjunto de objetos que representam suas assinaturas. Cada objeto conterá informações sobre a assinatura, como o ID, a data de criação, o tipo e se a assinatura está ou não ativa no momento. Veja a seguir o exemplo de uma resposta:

Para criar uma nova assinatura, faça uma solicitação POST para webhooks/v3/{appId}/subscriptions.

No corpo da solicitação, você pode incluir os seguintes campos:

CampoDescription
eventTypeO tipo de assinatura.
propertyNameO nome da propriedade em que a assinatura monitorará as alterações. Isso é necessário apenas para tipos de assinatura de alteração de propriedade.
inteligenteIndica se a assinatura está ativada e disparando notificações de forma ativa. O valor pode ser true ou false.

Não é necessário incluir id, createdAt ou createdBy, pois esses campos são definidos automaticamente.

Por exemplo, o corpo da solicitação pode ser parecido com o seguinte:

O eventType deve ser um tipo de assinatura válido, conforme definido na seção acima, e propertyName deve ser um nome de propriedade válido. Se um cliente não tiver uma propriedade definida que corresponda a esse valor, essa assinatura não resultará em notificação.

Para ativar ou pausar uma assinatura, faça uma solicitação PUT para webhooks/v3/{appId}/subscriptions/{subscriptionId}.

No corpo da solicitação, inclua o seguinte:

CampoDescription
inteligenteIndica se a assinatura está ativada e disparando notificações de forma ativa. O valor pode ser true ou false.

Para excluir uma assinatura, faça uma solicitação DELETE para webhooks/v3/{appId}/subscriptions/{subscriptionId}.

O ponto de extremidade na URL de destino especificada nas configurações de webhooks do aplicativo receberá do HubSpot solicitações POST contendo dados em formato JSON.

Para garantir que as solicitações que você está recebendo no ponto de extremidade do webhook sejam provenientes do HubSpot, o HubSpot preenche um cabeçalho X-HubSpot-Signature com um hash SHA-256 criado usando o segredo do cliente do seu aplicativo combinado com os detalhes da solicitação. Saiba mais sobre como validar assinaturas de solicitação.

Use as tabelas abaixo para visualizar detalhes sobre os campos que podem estar contidos no conteúdo.

CampoDescription
objectIdO ID do objeto que foi criado, alterado ou excluído. Para contatos, é o ID do contato; para empresas, é o ID da empresa; para negócios, é o ID do negócio; e para conversas, é o ID do thread.
propertyNameÉ enviado apenas para assinaturas de alteração de propriedade e é o nome da propriedade que foi alterada.
propertyValueÉ enviado apenas para assinaturas de alteração de propriedade e representa o novo valor definido para a propriedade que disparou a notificação.
changeSourceA origem da alteração. Pode ser qualquer uma das origens de alteração que aparecem nos históricos de propriedades de contato.
eventIdO ID do evento que disparou essa notificação. Não há garantias de que esse valor seja exclusivo.
subscriptionIdO ID da assinatura que disparou uma notificação sobre o evento.
portalIdO ID da conta da HubSpot do cliente onde o evento ocorreu.
appIdO ID do aplicativo. Isso é usado caso você tenha vários aplicativos apontando para a mesmo URL de Webhook.
occurredAtQuando esse evento ocorreu, como uma marca de data/hora em milissegundos.
eventTypeO tipo de evento para o qual esta notificação se destina. Revise a lista de tipos de assinatura permitidos na seção de assinatura de webhooks acima.
attemptNumberComeçando em 0, o número desta tentativa de notificação do seu serviço sobre esse evento. Se o serviço atingir o tempo limite ou lançar um erro conforme descrito na seção Tentativas abaixo, o HubSpot tentará enviar a notificação novamente.
messageIdSomente será enviado quando um webhook estiver monitorando novas mensagens para um thread. É o ID da nova mensagem.
messageTypeSomente será enviado quando um webhook estiver monitorando novas mensagens para um thread. Representa o tipo de mensagem que você está enviando. Este valor pode ser MESSAGE ou COMMENT.
CampoDescription
primaryObjectIdO ID do vencedor da mesclagem, que é o registro que permanece após a mesclagem. Na interface de mesclagem do HubSpot, é o registro à direita.
mergedObjectIdsUma matriz de IDs que representam os registros mesclados no vencedor da mesclagem. Na interface de mesclagem do HubSpot, é o registro à esquerda.
newObjectIdO ID do registro criado como resultado da mesclagem. Isso é separado do primaryObjectId porque, em alguns casos, um novo registro é criado como resultado da mesclagem.
numberOfPropertiesMovedUm número inteiro que representa quantas propriedades foram transferidas durante a mesclagem.
CampoDescription
associationTypeO tipo de associação, que será um dos seguintes:
  • CONTACT_TO_COMPANY
  • CONTACT_TO_DEAL
  • CONTACT_TO_TICKET
  • CONTACT_TO_CONTACT

  • COMPANY_TO_CONTACT
  • COMPANY_TO_DEAL
  • COMPANY_TO_TICKET
  • COMPANY_TO_COMPANY

  • DEAL_TO_CONTACT
  • DEAL_TO_COMPANY
  • DEAL_TO_LINE_ITEM
  • DEAL_TO_TICKET
  • DEAL_TO_DEAL

  • TICKET_TO_CONTACT
  • TICKET_TO_COMPANY
  • TICKET_TO_DEAL
  • TICKET_TO_TICKET

  • LINE_ITEM_TO_DEAL
fromObjectIdO ID do registro do qual a alteração da associação foi feita.
toObjectIdO ID do registro secundário no evento de associação.
associationRemovedUm booleano que representa o seguinte:
  • true: o webhook foi disparado pela remoção de uma associação.
  • false: o webhook foi disparado pela criação de uma associação.
isPrimaryAssociationUm booleano que representa o seguinte:
  • true: o registro secundário é a associação principal do registro do qual a alteração da associação foi feita.
  • false: o registro não é a associação principal do registro do qual a alteração da associação foi feita.
Observação: a criação de uma instância de associação principal entre dois registros de objeto fará com que a associação correspondente, que não seja a principal, também seja criada. Isso pode resultar em duas mensagens de webhook.

Como mostrado acima, você deve esperar receber um array de objetos em uma única solicitação. O tamanho do lote pode variar, mas será de no máximo 100 notificações. O HubSpot somente enviará várias notificações quando muitos eventos ocorrerem em um curto período de tempo. Por exemplo, se você tiver inscrito novos contatos e um cliente importar um grande número de contatos, o HubSpot enviará as notificações desses contatos importados em lotes, e não uma por solicitação.

O HubSpot não garante que você receberá essas notificações na ordem em que ocorreram. Use a propriedade occurredAt para cada notificação a fim de determinar quando o evento que disparou a notificação ocorreu.

O HubSpot também não garante que você receberá somente uma notificação para cada evento. Pode acontecer de o HubSpot enviar a mesma notificação várias vezes, embora isso provavelmente não ocorrerá.

Usuários do HubSpot podem excluir permanentemente um registro de contato para cumprir as leis de privacidade. Saiba mais sobre como realizar uma exclusão em conformidade com o GDPR.

Você pode se inscrever no tipo de assinatura contact.privacyDeletion para receber notificações de Webhook quando um usuário realizar a exclusão de um contato em conformidade com a privacidade.

As notificações de exclusão de privacidade têm comportamentos especiais:

  • Um evento de exclusão de privacidade também disparará o evento de exclusão de contato. Portanto, você receberá duas notificações se estiver inscrito nos dois eventos.
  • Essas notificações não serão necessariamente enviadas em uma ordem específica ou no mesmo lote de mensagens. Você precisará usar o ID do objeto para corresponder mensagens separadas.

Para garantir que as solicitações que você está recebendo no ponto de extremidade do webhook sejam provenientes do HubSpot, o HubSpot preenche um cabeçalho X-HubSpot-Signature com um hash SHA-256 da concatenação do segredo do aplicativo e do corpo da solicitação que estamos enviando.

Para verificar essa assinatura, concatene o segredo do aplicativo e o corpo de solicitação não analisado da solicitação que você está gerenciando e obtenha um hash SHA-256 do resultado. Compare o hash resultante com o valor do cabeçalho X-HubSpot-Signature. Se esses valores corresponderem, isso confirmará que essa solicitação veio da HubSpot. Ou a solicitação veio de outra pessoa que conhece o segredo do seu aplicativo. É importante manter esse valor em segredo.

Se esses valores forem diferentes, essa solicitação pode ter sido alterada em trânsito ou alguém pode ter falsificado as notificações de webhook no seu ponto de extremidade.

Se, em algum momento, o serviço enfrentar problemas ao lidar com notificações, o HubSpot fará 10 tentativas de reenviar as notificações com falha.

O HubSpot tentará novamente nos seguintes casos:

  • Falha na conexão: se o HubSpot não conseguir estabelecer uma conexão http com a URL do webhook fornecida.
  • Tempo limite: se o serviço demorar mais de cinco segundos para enviar uma resposta a um lote de notificações.
  • Códigos de erro: se o serviço responder com qualquer código de status HTTP (4xx ou 5xx).

As notificações serão repetidas até 10 vezes. Essas tentativas serão divulgadas nas próximas 24 horas, com atrasos variáveis entre solicitações. Será aplicada uma randomização às notificações individuais para evitar que um grande número de falhas simultâneas sejam repetidas exatamente mesmo horário.

As solicitações POST que o HubSpot envia ao seu serviço por meio das assinaturas de webhook não serão contabilizadas nos limites de taxa de API do aplicativo.

Você pode criar no máximo de 1.000 assinaturas por aplicativo. Se tentar criar mais de 1.000 assinaturas, você receberá uma solicitação 400 inválida com a seguinte mensagem: