Saltar para o conteúdo principal
A URL do seu webhook é pública, então qualquer pessoa que a descubra pode enviar solicitações para ela. A Ciarem assina cada solicitação com o segredo de assinatura do seu endpoint. Conferir essa assinatura é como o seu servidor distingue um evento real da Ciarem de um forjado. Verifique antes de confiar no corpo.

O segredo de assinatura

Cada endpoint tem seu próprio segredo. Ele começa com whsec_.
  • 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.
Trate-o como uma senha: guarde-o no seu gerenciador de segredos ou em uma variável de ambiente, nunca no código nem em um navegador.

O cabeçalho de assinatura

Cada solicitação carrega um cabeçalho Ciarem-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.
Se algum passo falhar, responda 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 id de evento, então remover duplicados pelo id deixa isso inofensivo.
  • Cada nova tentativa é assinada de novo. Uma entrega tentada de novo tem o mesmo corpo e o mesmo id de evento, mas um novo t e 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 id também.