Validar solicitações da HubSpot

Para garantir que as solicitações que sua integração esteja recebendo da HubSpot venham realmente da HubSpot, vários cabeçalhos são preenchidos na solicitação. Você pode usar esses cabeçalhos, juntamente com os campos da solicitação recebida, para verificar a assinatura da solicitação.

O método usado para verificar a assinatura depende da versão da assinatura.

• Para validar uma solicitação usando a versão mais recente da assinatura do HubSpot, use o cabeçalho X-HubSpot-Signature-V3 e siga as instruções associadas para validar a versão v3 da assinatura.
• Para compatibilidade com versões anteriores, as solicitações do HubSpot também incluem versões mais antigas da assinatura. Para validar uma versão mais antiga da assinatura, verifique o cabeçalho X-HubSpot-Signature-Version e siga as instruções associadas abaixo com base em se a versão é v1 ou v2.

Nas instruções abaixo, saiba como derivar um valor de hash do segredo do cliente do seu aplicativo e dos campos de uma solicitação recebida. Depois de calcular o valor do hash, você o comparará à assinatura. Se os dois forem iguais, a solicitação passará na validação. Caso contrário, a solicitação pode ter sido alterada em trânsito ou alguém pode estar falsificando solicitações para seu endpoint.

Se seu aplicativo estiver inscrito em eventos de objetos do CRM por meio da API do webhooks, as solicitações do HubSpot serão enviadas com o cabeçalho X-HubSpot-Signature-Version definido como v1. O cabeçalho X-HubSpot-Signature será um hash SHA-256 gerado usando o segredo do cliente do seu aplicativo combinado com detalhes da solicitação.

Para verificar a versão da assinatura, siga as seguintes etapas:

• Crie uma string que concatena o seguinte: Client secret + request body (se estiver presente)
• Crie um hash SHA-256 da string resultante.
• Compare o valor do hash com o valor do cabeçalho X-HubSpot-Signature:
  • Se forem iguais, essa solicitação passou na validação.
  • Se esses valores forem diferentes, essa solicitação pode ter sido alterada em trânsito ou alguém pode ter falsificado solicitações no seu endpoint.

Exemplo de uma solicitação com um corpo:

Exemplos de assinatura de solicitação v1: 

O hash resultante seria:
232db2615f3d666fe21a8ec971ac7b5402d33b9a925784df3ca654d05f4817de

Se seu aplicativo gerencia dados de uma ação de webhook em um fluxo de trabalho ou se você estiver retornando dados para um cartão de CRM personalizado, a solicitação do HubSpot será enviada com o cabeçalho X-HubSpot-Signature-Version definido como v2. O cabeçalho X-HubSpot-Signature será um hash SHA-256 gerado usando o segredo do cliente do seu aplicativo combinado com detalhes da solicitação.

Para verificar essa assinatura, execute as seguintes etapas:

• Crie uma string que concatena o seguinte: Client secret + http method + URI + request body (se estiver presente)
• Crie um hash SHA-256 da string resultante.
• Compare o valor do hash à assinatura.
  • Se forem iguais, essa solicitação passou na validação.
  • Se esses valores forem diferentes, essa solicitação pode ter sido alterada em trânsito ou alguém pode ter falsificado solicitações no seu endpoint.

• a URI usada para construir a string de origem deve corresponder exatamente à solicitação original, incluindo o protocolo. Se você tiver problemas para validar a assinatura, verifique se todos os parâmetros de consulta estão na mesma ordem em que foram listados na solicitação original.
• A string de origem deve ser de codificado em UTF-8 antes de calcular o hash SHA-256.

Exemplo de uma solicitação GET:

• Client secret : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
• HTTP Method: GET
• URI: https://www.example.com/webhook_uri

Exemplo de uma solicitação com um corpo:

• Client secret : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
• HTTP Method: POST
• URI: https://www.example.com/webhook_uri
• Request body: {"example_field":"example_value"} 

O cabeçalho X-HubSpot-Signature-v3 será um hash HMAC SHA-256 gerado usando o segredo do cliente do seu aplicativo combinado com detalhes da solicitação. Ela também conterá o cabeçalho X-HubSpot-Request-Timestamp.

Ao validar uma solicitação usando o cabeçalho X-HubSpot-Signature-v3, você precisará 

• Rejeitar a solicitação se o registro de data/hora tiver mais de 5 minutos.
• Na URI da solicitação, decodificar todos os caracteres codificados por URL listados na tabela abaixo. Você não precisa decodificar o ponto de interrogação que indica o início da string de consulta.

• Crie uma string codificada em utf-8 que concatena o seguinte: requestMethod + requestUri + requestBody + timestamp. O registro de data e hora é fornecido pelo cabeçalho X-HubSpot-Request-Timestamp.
• Crie um hash HMAC SHA-256 da string resultante usando o segredo do aplicativo como o segredo da função HMAC SHA-256.
• A Base64 codifica o resultado da função do HMAC.
• Compare o valor do hash à assinatura. Se forem iguais, a origem da solicitação foi confirmada como sendo da HubSpot. É recomendado usar uma comparação de string de tempo constante para proteger contra ataques de sincronização.