Usar webhooks com fluxos de trabalho do HubSpot

Use webhooks nos fluxos de trabalho para enviar ou recuperar informações entre a HubSpot e outras ferramentas externas. Há uma variedade de usos para webhooks. Exemplos de casos de uso populares para webhooks incluem:

• Publicação de dados de contato HubSpot em outro sistema, como um

• Enviando dados de negócio a um sistema externo de controle de entregas para criar uma ordem de compra.

• A recuperação de dados de outro sistema para atualizar seus registros do HubSpot.

Você pode enviar solicitações POST e GET usando fluxos de trabalho. O HubSpot regula o tráfego de webhook separadamente de outros processos de fluxo de trabalho. Isso é feito para simplificar o fluxo de trabalho e o desempenho do webhook. Quando um webhook estiver lento ou expirado, a ação do fluxo de trabalho poderá demorar mais do que o esperado para ser executada.

Observação: o HubSpot tentará novamente os webhooks com falha por até três dias, começando um minuto após a falha. As falhas subsequentes serão tentadas novamente em intervalos crescentes, com uma lacuna máxima de oito horas entre as tentativas. Os fluxos de trabalho não serão repetidos depois de receber códigos de status de resposta da série 4XX.
Uma exceção a esta regra são os erros de limite de taxa 429; os fluxos de trabalho serão repetidos automaticamente depois de receber uma resposta 429 e respeitarão o cabeçalho Retry-After, se estiver presente. Retry-After é gravado em milissegundos. Saiba sobre as exceções de código de erro específicas na Documentação para desenvolvedores da HubSpot.

Saiba mais sobre webhooks na documentação para desenvolvedores sobre webhooks. Se você tiver dúvidas sobre sua implementação específica de webhooks com o HubSpot, entre em contato com o HubSpot Developers Forums.

Configurar uma solicitação POST

1. No seu portal da HubSpot, acesse Automação > Fluxos de trabalho.
2. Para editar um fluxo de trabalho existente, clique no nome do fluxo de trabalho. Ou crie um novo fluxo de trabalho .
3. No editor de fluxo de trabalho, clique no + ícone de adição para adicionar uma ação.
4. No painel esquerdo, na seção Operações de dados, selecione Enviar um webhook.
    

5. Clique no menu suspenso Método e selecione POST.
6. Digite o URL do webhook.
   • As URLs de webhook estão restritas a um protocolo seguro e devem começar com HTTPS.
   • Para solicitar informações específicas, você pode adicionar parâmetros de consulta, como ?queryparameter=abc à URL do Webhook.
   • Se nenhum parâmetro de consulta tiver sido adicionado, uma solicitação genérica POST ou GET será enviada.
7. Configure seu tipo de autenticação para autenticar solicitações ao webhook. Você pode usar uma assinatura de solicitação no cabeçalho do webhook ou usar uma chave de API:
   • Para usar uma assinatura de solicitação no cabeçalho do webhook:
     • Clique no menu suspenso Tipo de autenticação. Em seguida, selecione Incluir assinatura de solicitação no cabeçalho.
     • Em seguida, insira sua ID de Aplicativo HubSpot. Saiba como verificar assinaturas de solicitação.
   • Para usar uma chave de API ou um aplicativo público criado por meio de uma conta de desenvolvedor para autenticação:
     • Ao utilizar uma chave de API para autenticação, o nome da chave de API e a localização da chave API usada dependerão de como o webhook foi configurado. Por motivos de segurança, a chave de API não será exibida em nenhuma solicitação de teste. Para utilizar uma chave de API:
       • Clique no menu suspenso Tipo de autenticação. Em seguida, selecione Chave de api .
       • Insira o nome da chave de API.
       • Clique no menu suspenso Chave de api . Em seguida, selecione Parâmetros de consulta ou Cabeçalho de solicitação. Saiba mais sobre como usar as chaves de API no HubSpot.
     • Se você estiver fazendo uma solicitação para APIs HubSpot:
       • Clique no menu suspenso chave de API e selecione um segredo. O valor secreto deve estar no formato Portador [YOUR_TOKEN].
       • Defina o valor do nome da chave de API para Autorização.
       • Defina o valor de Chave de api como Cabeçalho da Solicitação.
8. Para incluir todas as propriedades, selecione Incluir todas as propriedades de [objeto].
9. Para incluir somente propriedades específicas:
   • Selecione Personalizar corpo da solicitação.
   • Para personalizar o corpo da solicitação usando uma propriedade do HubSpot, insira a Chave e selecione uma propriedade. Para adicionar outra propriedade, clique em Adicionar propriedade.
   • Para personalizar o corpo da solicitação usando um campo estático, insira a Chave e o Valor. Para adicionar outra propriedade, clique em Adicionar valor estático.
   • Para remover uma propriedade ou valor estático, clique no ícone de lixeira delete.
10. Clique em Salvar.

Observação: para selecionar várias saídas, a resposta deve ser estruturada como um objeto JSON.

Configurar uma solicitação GET

1. No seu portal da HubSpot, acesse Automação > Fluxos de trabalho.
2. Para editar um fluxo de trabalho existente, clique no nome do fluxo de trabalho. Ou crie um novo fluxo de trabalho .
3. No editor de fluxo de trabalho, clique no + ícone de adição para adicionar uma ação.
4. No painel esquerdo, na seção Operações de dados, selecione Enviar um webhook.
    

5. Clique no menu suspenso Método e selecione GET.
6. Digite o URL do webhook.
   • As URLs de webhook estão restritas a um protocolo seguro e devem começar com HTTPS.
   • Para solicitar informações específicas, você pode adicionar parâmetros de consulta, como ?queryparameter=abc à URL do Webhook.
   • Se nenhum parâmetro de consulta tiver sido adicionado, uma solicitação genérica POST ou GET será enviada.
7. Configure seu tipo de autenticação para autenticar solicitações ao webhook. Você pode usar uma assinatura de solicitação no cabeçalho do webhook ou usar uma chave de API:
   • Para usar uma assinatura de solicitação no cabeçalho do webhook:
     • Clique no menu suspenso Tipo de autenticação. Em seguida, selecione Incluir assinatura de solicitação no cabeçalho.
     • Em seguida, insira sua ID de Aplicativo HubSpot. Saiba como verificar assinaturas de solicitação.
   • Para usar uma chave de API ou um aplicativo público criado por meio de uma conta de desenvolvedor para autenticação:
     • Ao utilizar uma chave de API para autenticação, o nome da chave de API e a localização da chave API usada dependerão de como o webhook foi configurado. Por motivos de segurança, a chave de API não será exibida em nenhuma solicitação de teste. Para utilizar uma chave de API:
       • Clique no menu suspenso Tipo de autenticação. Em seguida, selecione Chave de api .
       • Insira o nome da chave de API.
       • Clique no menu suspenso Chave de api . Em seguida, selecione Parâmetros de consulta ou Cabeçalho de solicitação. Saiba mais sobre como usar as chaves de API no HubSpot.
     • Se você estiver fazendo uma solicitação para APIs HubSpot:
       • Clique no menu suspenso chave de API e selecione um segredo. O valor secreto deve estar no formato Portador [YOUR_TOKEN].
       • Defina o valor do nome da chave de API para Autorização.
       • Defina o valor de Chave de api como Cabeçalho da Solicitação.
8. Se você estiver configurando uma solicitação GET, poderá usar as propriedades HubSpot ou adicionar valores estáticos como parâmetros de consulta: 

9. Para usar uma propriedade do HubSpot como parâmetro de consulta:
   • Na seção Parâmetros de consulta, insira a Chave e, em seguida, selecione a opção a propriedade .
   • Para adicionar outra propriedade, clique em Adicionar propriedade.
   • Para remover uma propriedade, clique no botão delete ícone excluir.
10. Para usar um valor estático como parâmetro de consulta:
    • Na seção Parâmetros de consulta, insira a Chave e digite um valor.
    • Para adicionar outra propriedade, clique em Adicionar valor estático.
    • Para remover uma propriedade, clique no botão delete ícone excluir.
11. Clique em Salvar.

Defina um limite de taxa para o seu webhook

Defina um limite de taxa para determinar com que rapidez a ação de webhook deve ser executada. O limite de taxa também afetará todas as seguintes ações no fluxo de trabalho.

1. No seu portal da HubSpot, acesse Automação > Fluxos de trabalho.
2. Clique no nome do fluxo de trabalho.
3. No editor de fluxo de trabalho, clique na ação Enviar um webhook.
4. No painel esquerdo, clique em Configurar limite de taxa para expandir a seção.
5. Clique para ativar ou desativar a opção Ativar limite de taxa . Por padrão, essa configuração está desativada. 
6. Configure seu limite de taxa: 
   • Execuções de ação: defina o número máximo de execuções por período de tempo. 
   • Cronograma: defina o cronograma para o seu limite de taxa. Você pode definir esse intervalo de tempo em Segundos, Minutos ou GerenciarHoras. 

Testar seu webhook no HubSpot

Ao configurar seu webhook POST ou GET, você pode executar um teste para ver a resposta do webhook. Durante o teste, mesmo que dados sejam enviados e recuperados de um terceiro, os registros existentes no HubSpot não são afetados. Ao usar uma chave de API para autenticação, ela não será exibida em nenhuma solicitação de teste.

Depois de testar o webhook, você pode selecionar quais campos serão gerados para serem usados como entradas posteriormente no fluxo de trabalho. Selecione somente as saídas disponíveis em cada resposta. Se a saída for utilizada em uma ação posterior, mas não estiver disponível na resposta, a ação irá falhar.

1. No seu portal da HubSpot, acesse Automação > Fluxos de trabalho.
2. Clique no nome do fluxo de trabalho.
3. No editor de fluxo de trabalho, clique na ação Enviar um webhook.
4. No painel esquerdo, clique em Testar ação para expandir a seção.
5. Se você estiver testando uma solicitação POST, a configuração do teste de webhook será diferente se você tiver optado por Personalizar o corpo da solicitação ou Incluir todas as propriedades de [objeto] na ação de webhook.
   • Se você tiver selecionado Personalizar corpo da solicitação, informe os valores de teste da propriedade para o seu teste.
   • Se você selecionou Incluir todas as propriedades de [objeto], clique no [objeto] menu suspenso e, em seguida, selecione a opção de teste com o.
6. Clique em Testar.
7. Para verificar os detalhes do webhook, selecione a guia Resposta ou Solicitação. Em cada guia, você pode clicar em Abrir tudo para expandir todas as seções ou Recolher tudo para recolher todas as seções.
   • Na guia Resposta, clique em cabeçalhos: ou corpo: para expandir cada seção.
   • Na guia Solicitação, clique em httpHeaders: para expandir a seção.
     
     

Testar seu webhook externamente

Depois de criar seu fluxo de trabalho com uma ação de webhook, você poderá executar um teste rápido com uma URL fictícia de webhook.

1. Em seu navegador, navegue até https://webhook.site e copie o URL exclusivo.
2. No campo de Webhook URL em sua ação de webhook, cole a URL.
3. Depois que o fluxo de trabalho for ativado, você poderá inscrever manualmente um contato de teste.
   
   

4. Ao testar seu webhook externamente:
   • Se uma ação do webhook for disparada com uma solicitação POST, um corpo de resposta JSON será enviado ao webhook com todas as informações sobre o contato, incluindo os envios de formulários, membros da lista e todos os valores da propriedade do contato. O sistema de recebimento pode, então, analisar os dados JSON e usá-los para seu próprio aplicativo.
   • Se uma ação do webhook for disparada com uma solicitação GET, uma solicitação genérica GET será enviada, a menos que parâmetros adicionais de consulta tenham sido aplicados.

Observação: os valores de propriedade antigos serão devolvidos apenas em fluxos de trabalho baseados em contato. Os webhooks usados em todos os outros tipos de fluxo de trabalho retornarão o valor mais recente.

Verificar assinaturas de solicitação em ganchos de fluxo de trabalho

Onde você selecionou Solicitar assinatura na seção Autenticação para sua ação de Acionamento de um webhook, o HubSpot preencherá o webhook com um cabeçalho X-HubSpot-Signature com um hash SHA-256 da concatenação do segredo do aplicativo para seu aplicativo, o método HTTP, o URI e o corpo não analisado. Saiba mais sobre isso na documentação dos desenvolvedores.

Para verificar se as solicitações recebidas no seu URL são do HubSpot:

• Possuir uma conta de desenvolvedor. Se você não tiver uma, inscreva-se para uma conta de desenvolvedor.
• Possuir um aplicativo. Se você não tiver um aplicativo, saiba como criar um aplicativo.
• Verifique o valor de hash da assinatura.

Disparar fluxos de trabalho a partir de webhooks

Os webhooks podem ser usados para disparar fluxos de trabalho. Quando os dados são alterados em um aplicativo de terceiros, isso pode gatilho um fluxo de trabalho. Saiba mais sobre como disparar fluxos de trabalho a partir de webhooks.

Usar dados do webhook no painel de dados

Os dados do webhook conectado à sua conta podem ser usados para determinadas ações no painel de dados.

Para usar dados do webhook conectado:

1. No seu portal da HubSpot, acesse Automação > Fluxos de trabalho.
2. Clique no nome do fluxo de trabalho.
3. Clique no ícone de adição + para adicionar uma ação.
4. No painel esquerdo, selecione uma ação que use o painel de dados.
5. No painel de dados, clique no menu suspenso Exibir propriedades ou resultados de ação de e selecione Gatilho de webhook. Em seguida, você poderá usar as propriedades do webhook conectado.