O segredo de assinatura
Cada endpoint tem seu próprio segredo. Ele começa comwhsec_.
- No painel: aparece quando você adiciona o endpoint, e de novo a qualquer momento na página do endpoint com Mostrar segredo. Só os administradores podem vê-lo.
- Com a API: retornado uma única vez, na resposta de
POST /v1/webhook-endpoints.
O cabeçalho de assinatura
Cada solicitação carrega um cabeçalhoCiarem-Signature:
A assinatura é calculada sobre o timestamp, um ponto e o corpo bruto da solicitação, usando o seu segredo de assinatura como chave:
Como verificar
1
Leia o corpo bruto
Pegue o corpo da solicitação exatamente como os bytes chegaram, antes de qualquer parsing de JSON. Fazer o parsing e serializar de novo muda o espaçamento e o escape de caracteres, e a assinatura deixa de bater.
2
Separe o cabeçalho
Separe
Ciarem-Signature por , e depois por = para obter t e v1.3
Calcule a assinatura esperada
Monte a mensagem
t + "." + raw body e calcule o HMAC-SHA256 dela com o seu segredo de assinatura. Use o segredo inteiro, incluindo o prefixo whsec_, como ele é.4
Compare com segurança
Compare o seu resultado com
v1 usando uma função de comparação em tempo constante, não ==.5
Confira o timestamp
Rejeite a solicitação se
t estiver a mais de 5 minutos do relógio do seu servidor. Isso impede que alguém capture uma solicitação real e a reenvie depois.400 e não faça nada com o corpo.
Código que você pode copiar
Confira seu código com um exemplo conhecido
Use estes valores para confirmar que o seu código de verificação calcula a assinatura certa, sem esperar por um evento real. Pule a checagem do timestamp enquanto roda isto, já que o timestamp do exemplo está no passado.
Você pode gerar o mesmo valor em um terminal:
Quando a assinatura falha
Boas práticas
- Um segredo por endpoint. Se você tem servidores de staging e de produção, dê a cada um o seu próprio endpoint, para que um segredo de staging vazado não possa forjar eventos de produção.
- Para trocar o segredo, substitua o endpoint. Um segredo não pode ser alterado no lugar. Para trocar, adicione um novo endpoint com a mesma URL e os mesmos eventos, atualize o seu servidor para aceitar o novo segredo e depois exclua o endpoint antigo. Enquanto os dois existem, você recebe cada evento duas vezes, uma por endpoint, com o mesmo
idde evento, então remover duplicados peloiddeixa isso inofensivo. - Cada nova tentativa é assinada de novo. Uma entrega tentada de novo tem o mesmo corpo e o mesmo
idde evento, mas um novote uma nova assinatura, então a checagem de 5 minutos também funciona para as novas tentativas. - A verificação prova a origem, não a unicidade. Um evento verificado ainda pode ser um duplicado. Remova duplicados pelo
idtambém.