Verifique se o webhook vem de Notiondesk

Verifique o cabeçalho X-ND-Signature nas solicitações do webhook Notiondesk com sua chave secreta de assinatura, com exemplos testados em Node.js e Python.

5 min de leitura

Cada solicitação de webhook é assinada com o segredo de assinatura do seu endpoint. Verifique a assinatura antes de confiar em uma solicitação, para que seu servidor atue somente em eventos que realmente vêm de Notiondesk e não foram alterados durante o transporte.

Caminho rápido: Leia o cabeçalho, calcule o HMAC SHA-256 com sua chave secreta de assinatura, compare-o e rejeite solicitações com mais de 5 minutos.tv1X-ND-Signature{t}.{raw body}v1

Antes de começar

  • Você tem o segredo de assinatura que copiou ao adicionar o endpoint. Ele começa com nd_whsec_. Se você o perdeu, rotacione-o. Consulte Rotacionar o segredo de assinatura .
  • O destinatário pode ler o corpo da solicitação exatamente como foi recebido, antes de qualquer análise JSON.

Como funciona a assinatura

Cada solicitação possui um cabeçalho X-ND-Signature:

X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb
Papel O que é isso?
tQuando a solicitação foi enviada, em segundos desde 1º de janeiro de 1970 (UTC). Cada nova tentativa recebe um novo t
v1O HMAC SHA-256 de t, um ponto e o corpo bruto da solicitação, assinado com seu segredo de assinatura e escrito em hexadecimal minúsculo.

Verificar uma solicitação

  1. Leia o corpo da requisição em formato bruto, como bytes. Não o analise previamente.
  1. Divida o cabeçalho X-ND-Signature por vírgulas e leia t e v1.
  1. Construa o texto assinado: t, um ponto, e então o corpo bruto. Por exemplo, 1794955939.{"id":"019a8f2e-...",...}.
  1. Calcule o HMAC SHA-256 desse texto com sua chave secreta de assinatura completa, incluindo nd_whsec_, e escreva-o em hexadecimal minúsculo.
  1. Compare seu resultado com v1 usando uma comparação de tempo constante.
  1. Verifique se t está dentro de 5 minutos do horário do seu servidor.
  1. Se alguma verificação falhar, responda 400 e ignore a solicitação. Se todas forem bem-sucedidas, responda 200 e trate o evento.

Exemplo de Node.js

Isso funciona com Node.js 18 ou posterior e Express. express.raw mantém o corpo como bytes brutos, o que a assinatura exige.

Exemplo em Python

Isso funciona com Python 3.9 ou posterior e Flask. request.get_data() retorna o corpo bruto.

Gire o segredo de assinatura

Gire o segredo caso ele tenha vazado ou se você o perdeu.

const crypto = require('crypto');
const express = require('express');

function verifyNotiondeskSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    String(header ?? '').split(',').map((part) => part.trim().split('=')),
  );
  if (!/^\d+$/.test(parts.t ?? '') || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.`)
    .update(rawBody)
    .digest('hex');

  const received = Buffer.from(parts.v1);
  const computed = Buffer.from(expected);
  return received.length === computed.length && crypto.timingSafeEqual(received, computed);
}

const app = express();

app.post('/webhooks/notiondesk', express.raw({ type: 'application/json' }), (req, res) => {
  const valid = verifyNotiondeskSignature(
    req.body,
    req.get('X-ND-Signature'),
    process.env.NOTIONDESK_WEBHOOK_SECRET,
  );
  if (!valid) return res.sendStatus(400);

  res.sendStatus(200);
  const event = JSON.parse(req.body);
  console.log('Received', event.event, event.id);
});

app.listen(3000);
import hashlib
import hmac
import os
import time

from flask import Flask, request

app = Flask(__name__)


def verify_notiondesk_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    try:
        parts = dict(part.strip().split("=", 1) for part in header.split(","))
        timestamp = int(parts["t"])
        received = parts["v1"]
    except (AttributeError, KeyError, ValueError):
        return False

    if abs(time.time() - timestamp) > tolerance:
        return False

    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)


@app.post("/webhooks/notiondesk")
def notiondesk_webhook():
    valid = verify_notiondesk_signature(
        request.get_data(),
        request.headers.get("X-ND-Signature", ""),
        os.environ["NOTIONDESK_WEBHOOK_SECRET"],
    )
    if not valid:
        return "", 400

    event = request.get_json()
    print("Received", event["event"], event["id"])
    return "", 200
  1. Abra o endpoint em Configurações > Desenvolvedores > Webhooks .
  1. Em Segredo de assinatura , clique em Girar e, em seguida, clique em Girar novamente para confirmar.
  1. Copie o novo segredo, armazene-o em seu servidor e clique em "Salvei" .
O segredo antigo deixa de funcionar imediatamente. Todas as solicitações enviadas após a rotação, incluindo novas tentativas de eventos anteriores, são assinadas com o novo segredo, portanto, atualize seu servidor ao mesmo tempo.

Se algumas solicitações falharem durante a troca, elas serão repetidas após 1 minuto com a nova chave secreta.

Erros comuns

  • Verificando o JSON analisado em vez do corpo bruto. Analisar o corpo e convertê-lo novamente em texto altera o espaçamento e os caracteres de escape, de modo que a assinatura não corresponde mais. Verifique os bytes recebidos e, em seguida, analise-os.
  • Usando a chave secreta incorreta. Cada endpoint possui sua própria chave secreta. Use o valor completo, incluindo nd_whsec_, e o mais recente, caso tenha sido rotacionado.
  • Um relógio do servidor incorreto. Se o relógio do seu servidor estiver atrasado em mais de alguns minutos, as solicitações válidas parecerão muito antigas. Mantenha o relógio sincronizado, por exemplo, com o NTP.
  • Comparando com uma simples verificação de igualdade. Use uma comparação de tempo constante, como crypto.timingSafeEqual em Node.js ou hmac.compare_digest em Python.

Perguntas frequentes

Por que rejeitar solicitações com mais de 5 minutos?

Uma solicitação capturada pode ser enviada ao seu servidor novamente mais tarde. A verificação de t limita isso a um curto período. Cada nova tentativa é assinada novamente com um novo t, portanto, as novas tentativas ainda são bem-sucedidas.

O evento de teste está assinado?

Sim. Clique em "Enviar evento de teste" na página do endpoint para verificar seu código de verificação. Um "200" em "Entregas recentes" significa que a verificação foi aprovada.

Posso ver o segredo da assinatura novamente?

Não. Ele é exibido apenas uma vez, quando você adiciona o endpoint ou rotaciona o segredo. A página do endpoint mostra apenas os primeiros caracteres.

Todos os meus endpoints compartilham um segredo?

Não. Cada endpoint possui sua própria chave secreta de assinatura, portanto, verifique cada solicitação com a chave secreta do endpoint para o qual ela foi enviada.

Artigos relacionados

Esta página foi útil?

Still need help? Ask us