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.
tv1X-ND-Signature{t}.{raw body}v1Antes 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? |
|---|---|
t | Quando a solicitação foi enviada, em segundos desde 1º de janeiro de 1970 (UTC). Cada nova tentativa recebe um novo t |
v1 | O 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
- Leia o corpo da requisição em formato bruto, como bytes. Não o analise previamente.
- Divida o cabeçalho
X-ND-Signaturepor vírgulas e leiatev1.
- Construa o texto assinado:
t, um ponto, e então o corpo bruto. Por exemplo,1794955939.{"id":"019a8f2e-...",...}.
- Calcule o HMAC SHA-256 desse texto com sua chave secreta de assinatura completa, incluindo
nd_whsec_, e escreva-o em hexadecimal minúsculo.
- Compare seu resultado com
v1usando uma comparação de tempo constante.
- Verifique se
testá dentro de 5 minutos do horário do seu servidor.
- Se alguma verificação falhar, responda
400e ignore a solicitação. Se todas forem bem-sucedidas, responda200e 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- Abra o endpoint em Configurações > Desenvolvedores > Webhooks .
- Em Segredo de assinatura , clique em Girar e, em seguida, clique em Girar novamente para confirmar.
- Copie o novo segredo, armazene-o em seu servidor e clique em "Salvei" .
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.timingSafeEqualem Node.js ouhmac.compare_digestem 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.