Conferir a assinatura

Todo envio de um webhook — e de uma ação Enviar para outro sistema com Assinar o envio — leva o cabeçalho:

X-Tai-Assinatura: t=1791374691,v1=5f0c9a…e41b

• t é o instante da assinatura, em segundos desde 1970 (UTC).
• v1 é o HMAC-SHA256, em hexadecimal minúsculo, do texto <t>.<corpo>, com o segredo do webhook como chave. O corpo é o texto exato recebido, byte a byte.

Como conferir

1. Leia o corpo cru, antes de qualquer parse de JSON.
2. Separe t e v1 do cabeçalho.
3. Calcule HMAC-SHA256(segredo, t + "." + corpo) em hexadecimal.
4. Compare com v1 em tempo constante.
5. Recuse se t estiver longe do seu relógio — 5 minutos é uma boa tolerância.

Node.js

import crypto from 'node:crypto'
import express from 'express'

const SEGREDO = process.env.TAI_WEBHOOK_SECRET
const app = express()

app.post('/tai/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const cabecalho = req.get('X-Tai-Assinatura') ?? ''
  const partes = Object.fromEntries(cabecalho.split(',').map((p) => p.trim().split('=')))
  const t = Number(partes.t)
  const corpo = req.body.toString('utf8')

  const esperado = crypto.createHmac('sha256', SEGREDO).update(`${t}.${corpo}`).digest('hex')
  const valida =
    partes.v1?.length === esperado.length &&
    crypto.timingSafeEqual(Buffer.from(partes.v1), Buffer.from(esperado))
  if (!valida || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(401)

  const evento = JSON.parse(corpo)
  fila.publicar(req.get('X-Tai-Entrega'), evento) // processe depois
  res.sendStatus(204)
})

Python

import hashlib, hmac, os, time
from flask import Flask, request, abort

SEGREDO = os.environ["TAI_WEBHOOK_SECRET"].encode()
app = Flask(__name__)

@app.post("/tai/webhook")
def receber():
    partes = dict(p.strip().split("=", 1) for p in request.headers.get("X-Tai-Assinatura", "").split(",") if "=" in p)
    t = partes.get("t", "0")
    corpo = request.get_data()  # bytes crus

    esperado = hmac.new(SEGREDO, t.encode() + b"." + corpo, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(esperado, partes.get("v1", "")) or abs(time.time() - int(t)) > 300:
        abort(401)

    fila.publicar(request.headers["X-Tai-Entrega"], request.get_json())  # processe depois
    return "", 204

Cuidado

Calcule sobre o corpo cru. Reformatar o JSON (espaços, ordem das chaves, acentos escapados) muda o HMAC e a assinatura deixa de bater.

Trocar o segredo

Na aba Webhooks, Gerar outro segredo gera um segredo novo, mostrado uma única vez; a partir dali os envios saem com ele. Atualize o seu sistema logo em seguida — ou aceite os dois segredos por alguns minutos durante a troca.

Sem assinatura

As ações dos gatilhos do Atendimento e as ações Enviar para outro sistema sem Assinar o envio não levam X-Tai-Assinatura. Nesses casos, autentique por um cabeçalho com token (nas ações que aceitam cabeçalhos) ou por um segredo no caminho da URL.