Verificar Assinaturas de Webhooks

Esta página descreve como verificar assinaturas de webhooks do Xtremepush ao usar o tipo de autenticação Signed Payload .

Cabeçalho de Assinatura Webhook

O Xtremepush inclui um cabeçalho HTTP, X-Xtremepush-Signature, em cada requisição de webhook, como mostrado no exemplo abaixo:

X-Xtremepush-Signature:
t=1689343556,
v1=2c709b15aee216e2d7097cb57b7c5b422bea3fd938589dafab265506f7651011,
v1=874f7108d19848f35f3e70a4751ee2bfae164f4cc74259c405275c235963a141

Este cabeçalho contém dois componentes:

1. Timestamp (t=...): Indica quando o webhook foi enviado. Como esse carimbo de tempo faz parte da carga útil assinada, ele também é verificado pela assinatura. Portanto, um atacante não pode alterar o carimbo de data sem invalidar a assinatura. Se a assinatura for válida, mas o carimbo de data for muito antigo, sua aplicação deve rejeitar o payload.

2. Assinatura (v1=...): Uma assinatura gerada usando seu segredo de assinatura único. Esse segredo é fornecido no campo Webhook Secret Key nas configurações de integração do seu webhook. O Xtremepush gera assinaturas usando um código de autenticação de mensagens baseado em hash (HMAC) com SHA-256. Para evitar ataques de downgrade, você deve ignorar todos os esquemas que não sejam a versão atual (v1).

Você deve verificar o webhook criando sua própria assinatura com os mesmos dados e chave secreta. Se sua assinatura gerada coincidir com a enviada pelo Xtremepush, o pedido é considerado autêntico e pode ser confiável.

Tratamento de Assinaturas Múltiplas

Você só pode ter uma chave secreta ativa por vez. Quando você gera uma nova chave a partir das configurações de integração do webhook, ela imediatamente substitui a anterior.

O Xtremepush mantém o segredo anterior ativo por até 24 horas. Durante esse tempo, o Xtremepush gera uma assinatura tanto para o novo quanto para o antigo segredo, e seu endpoint receberá ambos no cabeçalho da requisição.

Verifique a assinatura do Webhook

Siga estes passos para verificar as assinaturas dos webhooks.

1. Analise a X-Xtremepush-Signature sequência do cabeçalho.

   1. Divida a string de cabeçalho pelo caractere vírgula (,) para obter uma lista de elementos.

   2. Divida cada elemento pelo caractere igual (=) para obter sua chave e valor.

   3. Armazene o valor da chave de carimbo de data (t) e todos os valores das chaves de assinatura v1

2. Prepare a signed_payload string concatenando o seguinte:

   • O carimbo de tempo (str)

   • Um ponto (.)

   • O corpo JSON do pedido

3. Determine a assinatura esperada calculando um HMAC com a função de hash SHA256.

   • chave: Use o segredo de assinatura do seu endpoint

   • Mensagem: Use a signed_payload string que você criou no Passo 2.

4. Compare Assinaturas e Valide

   1. Compare a assinatura (ou assinaturas) no cabeçalho com a assinatura esperada

   2. Se uma assinatura coincidir, calcule a diferença entre o carimbo de tempo atual e o carimbo de tempo recebido para decidir se está dentro da sua tolerância aceitável.
      Para se proteger contra ataques de temporização, use uma comparação de strings em tempo constante para comparar a assinatura esperada com cada uma das assinaturas recebidas.