Webhooks

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 endpoint que você configurar. Você pode configurar eventos assinados nas configurações de seu aplicativo ou usando os endpoints 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 endpoint 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 crm.objects.contacts.read. O aplicativo precisará ser configurado para exigir que o escopo conversations.read seja inscrito nos eventos de conversas.

Você deve configurar esses escopos antes de criar uma assinatura do webhook. Revise a documentação de OAuth para obter mais detalhes sobre os escopos e configurar o URL de autorização para o seu aplicativo.

Se o aplicativo já estiver usando webhooks, você não poderá remover o escopo crm.objects.contacts.read ou conversations.read até remover todas as assinaturas de webhook do 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. 
  
• 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. 

• Clique em Salvar. 

Você pode usar os seguintes endpoints e suachave 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:

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:

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. 

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: 

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: 

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. 

• 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. 

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

O objeto de assinatura pode incluir os seguintes campos:

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:

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.

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

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

O endpoint 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 endpoint 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.

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 endpoint 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 endpoint.

Saiba mais sobre como validar solicitações de assinatura. 

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: