Pular para o conteúdo principal

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:

  1. Leia o corpo bruto (bytes), antes de qualquer conversão para JSON.
  2. Calcule o HMAC-SHA256 dele com o segredo.
  3. Compare com o valor recebido, sem o prefixo sha256=, usando comparação de tempo constante.
Sobre o X-Webhook-Timestamp

O 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​

ProblemaCausa provávelSolução
A assinatura nunca bateO framework converteu o corpo para JSON antes da conferência, e o JSON reserializado muda espaços ou a ordem dos camposCalcule o HMAC sobre o corpo bruto (bytes)
A assinatura nunca bateO segredo foi trocado na tela e o seu sistema ainda usa o antigoAtualize o segredo no seu sistema
O cabeçalho não chegaA assinatura foi cadastrada sem segredoEdite a assinatura e cadastre um segredo
A assinatura bate só às vezesO cálculo inclui o X-Webhook-TimestampUse só o corpo bruto
Ainda com dúvida?

A nossa equipe ajuda você a configurar e usar esse recurso.