Validação da assinatura
Quando a assinatura do webhook tem um segredo cadastrado, todo aviso traz o cabeçalho X-Webhook-Signature. Conferir esse cabeçalho garante que o aviso veio do Tesselys e que o corpo não foi alterado no caminho. Sem segredo cadastrado, o cabeçalho não é enviado.
Como a assinatura é calculada
X-Webhook-Signature = "sha256=" + hex( HMAC-SHA256( segredo, corpo_bruto ) )
- A chave do HMAC é o segredo que você cadastrou na assinatura.
- A mensagem é o corpo bruto da requisição, exatamente como chegou, sem nenhum outro dado.
- O resultado vai em hexadecimal minúsculo, com o prefixo
sha256=.
Para conferir:
- Leia o corpo bruto (bytes), antes de qualquer conversão para JSON.
- Calcule o HMAC-SHA256 dele com o segredo.
- Compare com o valor recebido, sem o prefixo
sha256=, usando comparação de tempo constante.
Sobre o
X-Webhook-TimestampO cabeçalho X-Webhook-Timestamp informa quando a tentativa foi enviada, mas não entra na assinatura. Use-o só como informação. Para não processar o mesmo aviso duas vezes, guarde o X-Webhook-Delivery-Id.
Node.js (Express)
const crypto = require('crypto')
const express = require('express')
const app = express()
const SEGREDO = process.env.TESSELYS_WEBHOOK_SECRET
function assinaturaValida(corpoBruto, assinatura) {
if (!assinatura || !assinatura.startsWith('sha256=')) return false
const esperada = crypto.createHmac('sha256', SEGREDO).update(corpoBruto).digest('hex')
const recebida = assinatura.slice('sha256='.length)
const a = Buffer.from(esperada, 'hex')
const b = Buffer.from(recebida, 'hex')
return a.length === b.length && crypto.timingSafeEqual(a, b)
}
// express.raw mantém o corpo como Buffer, sem converter para JSON
app.post('/webhooks/tesselys', express.raw({ type: 'application/json' }), (req, res) => {
if (!assinaturaValida(req.body, req.get('X-Webhook-Signature'))) {
return res.status(401).json({ error: 'assinatura inválida' })
}
const aviso = JSON.parse(req.body.toString('utf-8'))
const entregaId = req.get('X-Webhook-Delivery-Id')
// Responda logo e processe depois (fila, tarefa em segundo plano)
res.status(200).json({ recebido: true })
processar(entregaId, aviso).catch(console.error)
})
async function processar(entregaId, aviso) {
// ignore entregaId já processado
switch (aviso.event) {
case 'person.created':
// sincronizar a pessoa aviso.data.id
break
case 'deal.status_changed':
if (aviso.data.newStatus === 'WINNER') {
// disparar o pós-venda
}
break
case 'financial_entry.paid':
// marcar o título aviso.data.id como pago
break
}
}
app.listen(3000)
Python (Flask)
import hashlib
import hmac
import os
from flask import Flask, jsonify, request
app = Flask(__name__)
SEGREDO = os.environ["TESSELYS_WEBHOOK_SECRET"].encode("utf-8")
def assinatura_valida(corpo_bruto: bytes, assinatura: str) -> bool:
if not assinatura or not assinatura.startswith("sha256="):
return False
esperada = hmac.new(SEGREDO, corpo_bruto, hashlib.sha256).hexdigest()
return hmac.compare_digest(esperada, assinatura[len("sha256="):])
@app.post("/webhooks/tesselys")
def receber():
corpo = request.get_data() # bytes, sem conversão
if not assinatura_valida(corpo, request.headers.get("X-Webhook-Signature", "")):
return jsonify({"error": "assinatura inválida"}), 401
aviso = request.get_json()
entrega_id = request.headers.get("X-Webhook-Delivery-Id")
# enfileire (entrega_id, aviso) e responda logo
return jsonify({"recebido": True}), 200
Problemas comuns
| Problema | Causa provável | Solução |
|---|---|---|
| A assinatura nunca bate | O framework converteu o corpo para JSON antes da conferência, e o JSON reserializado muda espaços ou a ordem dos campos | Calcule o HMAC sobre o corpo bruto (bytes) |
| A assinatura nunca bate | O segredo foi trocado na tela e o seu sistema ainda usa o antigo | Atualize o segredo no seu sistema |
| O cabeçalho não chega | A assinatura foi cadastrada sem segredo | Edite a assinatura e cadastre um segredo |
| A assinatura bate só às vezes | O cálculo inclui o X-Webhook-Timestamp | Use só o corpo bruto |
Ainda com dúvida?
A nossa equipe ajuda você a configurar e usar esse recurso.