API dos Webhooks

Última modificação: 28 de agosto de 2025

Run in Postman

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.

Observação:

Você também pode gerenciar webhooks em um aplicativo privado. Nos aplicativos privados, as configurações de webhook só podem ser editadas nas configurações do aplicativo privado; elas não podem ser editadas por meio da API.
Para se inscrever em webhooks de conversas, você precisa acessar a caixa de entrada de conversas e as APIs de mensagens, que estão atualmente em versão beta.

Escopos

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.

Configurações de webhooks

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.

Observação:

As configurações de Webhooks podem ser armazenadas no cache por até cinco minutos. Quando você altera o URL do webhook, os limites de simultaneidade ou as configurações de assinatura, essas alterações podem levar até cinco minutos para entrarem em vigor.
O HubSpot define um limite de simultaneidade de 10 solicitações ao enviar dados de eventos de assinatura associados a uma conta que instalou seu aplicativo. Esse limite de simultaneidade é o número máximo de solicitações em andamento que o HubSpot tentará por vez. Cada solicitação pode conter até 100 eventos.

Gerenciar configurações em sua conta de desenvolvedor

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.

Gerenciar configurações por meio da API

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:

Campo	Description
`webhookUrl`	A URL para a qual o HubSpot enviará notificações de webhook. A URL deve ser atendida por HTTPS.
`maxConcurrentRequests`	O 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:

Campo	Description
`targetUrl`	A URL disponível publicamente para que o HubSpot indique onde as payloads do evento serão entregues.
`acúmulo`	Configure os detalhes de acúmulo do webhook neste objeto. O objeto de acúmulo inclui os campos `period` e `maxConcurrentRequests`.
`período`	Escala de tempo para esta configuração. Pode ser `SECONDLY` (por segundo) ou `ROLLING_MINUTE` (por minuto).
`maxConcurrentRequests`	O 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:

// PUT request to https://api.hubapi.com/webhooks/v3/{appId}/settings

{
  "throttling": {
    "period": "SECONDLY",
    "maxConcurrentRequests": 10
  },
  "targetUrl": "https://www.example.com/hubspot/target"
}

Assinaturas de Webhook

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 assinatura	Escopo obrigatório	Descrição
`contact.creation`	`crm.objects.contacts.read`	Receba uma notificação se um contato for criado na conta de um cliente.
`contact.deletion`	Receba uma notificação se um contato for excluído na conta de um cliente.
`contact.merge`	Receba uma notificação se um contato for mesclado com outro.
`contact.associationChange`	Receba 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.restore`	Receba uma notificação se um contato for restaurado da exclusão.
`contact.privacyDeletion`	Receba uma notificação se um contato for excluído por motivos de conformidade com a privacidade.
`contact.propertyChange`	Receba uma notificação se uma propriedade específica for alterada para um contato em uma conta.
`company.creation`	`crm.objects.companies.read`	Receba uma notificação se uma empresa for criada na conta de um cliente.
`company.deletion`	Receba uma notificação se uma empresa for excluída na conta de um cliente.
`company.propertyChange`	Receba uma notificação se uma propriedade específica for alterada para uma empresa na conta de um cliente.
`company.associationChange`		Receba 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.restore`		Receba uma notificação se uma empresa for restaurada da exclusão.
`company.merge`		Receba uma notificação se uma empresa for mesclada com outra.
`deal.creation`	`crm.objects.deals.read`	Receba uma notificação se um negócio for criado na conta de um cliente.
`deal.deletion`	Receba uma notificação se um negócio for excluído na conta de um cliente.
`deal.associationChange`	Receba 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.restore`	Receba uma notificação se um negócio for restaurado da exclusão.
`deal.merge`	Receba uma notificação se um negócio for mesclado com outro.
`deal.propertyChange`	Receba uma notificação se uma propriedade específica for alterada para um negócio na conta de um cliente.
`ticket.creation`	`tickets`	Receba uma notificação se um ticket for criado na conta de um cliente.
`ticket.deletion`	Receba uma notificação se um ticket for excluído na conta de um cliente.
`ticket.propertyChange`	Receba uma notificação se uma propriedade específica for alterada para um ticket na conta de um cliente.
`ticket.associationChange`		Receba 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.restore`		Receba uma notificação se um tíquete for restaurado da exclusão.
`ticket.merge`		Receba uma notificação se um ticket for mesclado com outro.
`product.creation`	`e-commerce`	Receba uma notificação se um produto for criado na conta de um cliente.
`product.deletion`	Receba uma notificação se um produto for excluído na conta de um cliente.
`product.restore`	Receba uma notificação se um produto for restaurado da exclusão.
`product.merge`	Receba uma notificação se um produto for mesclado com outro.
`product.propertyChange`	Receba uma notificação se um produto específico for alterado para um produto na conta de um cliente.
`line_item.creation`	Receba uma notificação se um item de linha for criado na conta de um cliente.
`line_item.deletion`	Receba uma notificação se um item de linha for excluído na conta de um cliente.
`line_item.associationChange`	Receba 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.restore`	Receba uma notificação se um item de linha for restaurado da exclusão.
`line_item.merge`	Receba uma notificação se um item de linha for mesclado com outro.
`line_item.propertyChange`	Receba 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 assinatura	Scope	Descrição
`conversation.creation`	`conversations.read`	Receba uma notificação se um novo thread for criado em uma conta.
`conversation.deletion`	Receba uma notificação se um thread for arquivado ou excluído de forma reversível em uma conta.
`conversation.privacyDeletion`	Receba uma notificação se um thread for excluído permanentemente em uma conta.
`conversation.propertyChange`	Receba uma notificação se uma propriedade em um thread for alterada.
`conversation.newMessage`	Receba 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.

Criar assinaturas em sua conta de desenvolvedor

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.

Criar assinaturas por meio da API

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:

Campo	Description
`id`	Um número que representa o ID exclusivo de uma assinatura.
`createdAt`	A hora em milissegundos em que essa assinatura foi criada.
`createdBy`	O ID associado ao usuário que criou a assinatura.
`inteligente`	Indica se a assinatura está ativada e disparando notificações de forma ativa. O valor pode ser `true` ou `false`.
`eventType`	O tipo de assinatura. A tabela no início desta seção inclui os tipos de assinatura disponíveis.
`propertyName`	O nome da propriedade em que a assinatura monitorará as alterações. Isso é necessário apenas para tipos de assinatura de alteração de propriedade.

Obter assinaturas

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:

// Example GET request to https://api.hubapi.com/webhooks/v3/{appId}/subscriptions

[
  {
    "id": 25,
    "createdAt": 1461704185000,
    "createdBy": 529872,
    "eventType": "contact.propertyChange",
    "propertyName": "lifecyclestage",
    "active": false
  },
  {
    "id": 59,
    "createdAt": 1462388498000,
    "createdBy": 529872,
    "eventType": "company.creation",
    "active": false
  },
  {
    "id": 108,
    "createdAt": 1463423132000,
    "createdBy": 529872,
    "eventType": "deal.creation",
    "active": true
  }
]

Criar uma nova assinatura

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:

Campo	Description
`eventType`	O tipo de assinatura.
`propertyName`	O nome da propriedade em que a assinatura monitorará as alterações. Isso é necessário apenas para tipos de assinatura de alteração de propriedade.
`inteligente`	Indica 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:

// Example POST request to https://api.hubapi.com/webhooks/v3/{appId}/subscriptions

{
  "eventType": "company.propertyChange",
  "propertyName": "companyname",
  "active": false
}

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.

Atualizar uma assinatura

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:

Campo	Description
`inteligente`	Indica se a assinatura está ativada e disparando notificações de forma ativa. O valor pode ser `true` ou `false`.

Excluir uma assinatura

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

Payloads de webhooks

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.

Campo	Description
`objectId`	O 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.
`changeSource`	A origem da alteração. Pode ser qualquer uma das origens de alteração que aparecem nos históricos de propriedades de contato.
`eventId`	O ID do evento que disparou essa notificação. Não há garantias de que esse valor seja exclusivo.
`subscriptionId`	O ID da assinatura que disparou uma notificação sobre o evento.
`portalId`	O ID da conta da HubSpot do cliente onde o evento ocorreu.
`appId`	O ID do aplicativo. Isso é usado caso você tenha vários aplicativos apontando para a mesmo URL de Webhook.
`occurredAt`	Quando esse evento ocorreu, como uma marca de data/hora em milissegundos.
`eventType`	O 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.
`attemptNumber`	Começ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.
`messageId`	Somente será enviado quando um webhook estiver monitorando novas mensagens para um thread. É o ID da nova mensagem.
`messageType`	Somente 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`.

Campo	Description
`primaryObjectId`	O ID do vencedor da mesclagem, que é o registro que permanece após a mesclagem. Na interface de mesclagem do HubSpot, é o registro à direita.
`mergedObjectIds`	Uma matriz de IDs que representam os registros mesclados no vencedor da mesclagem. Na interface de mesclagem do HubSpot, é o registro à esquerda.
`newObjectId`	O ID do registro criado como resultado da mesclagem. Isso é separado do `primaryObjectId` porque, em alguns casos, um novo registro é criado como resultado da mesclagem.
`numberOfPropertiesMoved`	Um número inteiro que representa quantas propriedades foram transferidas durante a mesclagem.

Campo	Description
`associationType`	O 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`
`fromObjectId`	O ID do registro do qual a alteração da associação foi feita.
`toObjectId`	O ID do registro secundário no evento de associação.
`associationRemoved`	Um 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.
`isPrimaryAssociation`	Um 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.

//
[
  {
    "objectId": 1246965,
    "propertyName": "lifecyclestage",
    "propertyValue": "subscriber",
    "changeSource": "ACADEMY",
    "eventId": 3816279340,
    "subscriptionId": 25,
    "portalId": 33,
    "appId": 1160452,
    "occurredAt": 1462216307945,
    "eventType": "contact.propertyChange",
    "attemptNumber": 0
  },
  {
    "objectId": 1246978,
    "changeSource": "IMPORT",
    "eventId": 3816279480,
    "subscriptionId": 22,
    "portalId": 33,
    "appId": 1160452,
    "occurredAt": 1462216307945,
    "eventType": "contact.creation",
    "attemptNumber": 0
  }
]

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

Exclusões de contatos em conformidade com a privacidade

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.

Segurança

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. Saiba mais sobre como validar solicitações de assinatura.

Tentativas

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.

Limites

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:

//
{
  "status": "error",
  "message": "Couldn't create another subscription. You've reached the maximum number allowed per application (1000).",
  "correlationId": "2c9beb86-387b-4ff6-96f7-dbb486c00a95",
  "requestId": "919c4c84f66769e53b2c5713d192fca7"
}

Webhooks v4

Webhooks v3

Run in Postman

Observação:

Escopos

Configurações de webhooks

Observação:

Gerenciar configurações em sua conta de desenvolvedor

Gerenciar configurações por meio da API

Assinaturas de Webhook

Criar assinaturas em sua conta de desenvolvedor

Criar assinaturas por meio da API

Obter assinaturas

Criar uma nova assinatura

Atualizar uma assinatura

Excluir uma assinatura

Payloads de webhooks

Exclusões de contatos em conformidade com a privacidade

Segurança

Tentativas

Limites

Webhooks v4

Webhooks v3

Run in Postman

​Observação:

​Escopos

​Configurações de webhooks

​Observação:

​Gerenciar configurações em sua conta de desenvolvedor

​Gerenciar configurações por meio da API

​Assinaturas de Webhook

​Criar assinaturas em sua conta de desenvolvedor

​Criar assinaturas por meio da API

​Obter assinaturas

​Criar uma nova assinatura

​Atualizar uma assinatura

​Excluir uma assinatura

​Payloads de webhooks

​Exclusões de contatos em conformidade com a privacidade

​Segurança

​Tentativas

​Limites

Observação:

Escopos

Configurações de webhooks

Observação:

Gerenciar configurações em sua conta de desenvolvedor

Gerenciar configurações por meio da API

Assinaturas de Webhook

Criar assinaturas em sua conta de desenvolvedor

Criar assinaturas por meio da API

Obter assinaturas

Criar uma nova assinatura

Atualizar uma assinatura

Excluir uma assinatura

Payloads de webhooks

Exclusões de contatos em conformidade com a privacidade

Segurança

Tentativas

Limites