Webhooks

Rascunho: especificação em definição. Endpoints e campos podem mudar.

Webhooks avisam a integração quando algo muda no caixa, sem necessidade de consultar a API em intervalos. Cada destino é cadastrado com POST /webhooks e recebe um segredo próprio para verificar a assinatura.

Eventos

Evento	Quando é enviado
`deposito.confirmado`	Um depósito de USDC numa carteira vinculada foi confirmado on-chain
`alocacao.proposta`	A TESA criou uma proposta de alocação ou de rebalanceamento, pendente de aprovação
`alocacao.aprovada`	A proposta foi aprovada e as transações estão prontas para assinatura no custodiante
`resgate.concluido`	O USDC do resgate chegou à carteira de destino, com confirmação on-chain
`rendimento.apurado`	O rendimento de um período foi fechado
`cobranca.emitida`	A cobrança de 5% sobre o yield do período foi emitida (ou o percentual do plano enterprise)

A proposta é que o destino possa assinar todos os eventos ou apenas uma lista deles.

Formato do payload

Todos os eventos têm o mesmo envelope. O campo dados traz o recurso no mesmo formato devolvido pela API.

Exemplo ilustrativo

{
  "id": "evt_7h2k9q",
  "tipo": "alocacao.proposta",
  "criado_em": "2026-09-01T09:30:05Z",
  "ambiente": "producao",
  "organizacao_id": "org_1a2b",
  "dados": {
    "id": "prop_8f2a1c",
    "tipo": "rebalanceamento",
    "status": "pendente",
    "movimentos": [
      { "de": "USDY", "para": "BUIDL", "valor": "42105.50" }
    ]
  }
}

Verificação de assinatura

Cada envio traz o cabeçalho Tesa-Signature no formato t=<timestamp>,v1=<assinatura>. A assinatura é o HMAC-SHA256, em hexadecimal, da string <timestamp>.<corpo bruto> com o segredo do destino.

Node.js

import crypto from "node:crypto";

function verificar(corpoBruto, cabecalho, segredo) {
  const partes = Object.fromEntries(
    cabecalho.split(",").map((p) => p.split("="))
  );
  const esperado = crypto
    .createHmac("sha256", segredo)
    .update(`${partes.t}.${corpoBruto}`)
    .digest("hex");

  const dentroDaJanela = Math.abs(Date.now() / 1000 - Number(partes.t)) < 300;
  const confere = crypto.timingSafeEqual(
    Buffer.from(esperado),
    Buffer.from(partes.v1)
  );
  return dentroDaJanela && confere;
}

Verifique a assinatura sobre o corpo bruto, antes de qualquer parse de JSON, e recuse eventos com mais de 5 minutos.

Entrega e reenvio

O destino deve responder com qualquer status 2xx em até 10 segundos. O processamento pesado deve acontecer depois da resposta.
Sem 2xx, a TESA reenvia com espera crescente: 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas e 12 horas. Depois disso o evento fica marcado como falho.
Eventos falhos podem ser consultados e reenviados pelo painel.
A entrega é pelo menos uma vez: o mesmo evento pode chegar mais de uma vez. Use o id do evento para descartar duplicatas.
A ordem de chegada não é garantida. Use criado_em e o status do recurso, ou consulte a API, antes de agir.

Webhook é aviso, não comando. Um evento alocacao.aprovada não move fundos sozinho: a movimentação só acontece depois da assinatura no custodiante da empresa.

Começando

Guias

Referência

Referência da API

Eventos

Formato do payload

Verificação de assinatura

Entrega e reenvio

​Eventos

​Formato do payload

​Verificação de assinatura

​Entrega e reenvio

Eventos

Formato do payload

Verificação de assinatura

Entrega e reenvio