Webhooks

A Tessela avisa o seu servidor quando algo acontece com uma cobrança, um estorno ou um repasse. Esta página explica o formato, a assinatura e o reenvio.

Atualizado em 14 out 2026

Visão geral

Webhooks são requisições POST que a Tessela envia para uma URL sua sempre que um evento acontece. Use webhooks em vez de consultar a API repetidamente: eles chegam em milissegundos e economizam chamadas.

Nota. Eventos de teste e de produção usam URLs separadas. Configure as duas no painel.

Formato do evento

Todo evento tem o mesmo envelope: um id único, o tipo, a data de criação e o objeto afetado em dados. O objeto vem completo, no estado em que estava quando o evento foi gerado.

cobranca.paga

{  "id": "evt_3Qm9XkT2pL7a",  "tipo": "cobranca.paga",  "criado_em": "2026-10-28T15:00:04Z",  "modo": "producao",  "dados": {    "id": "cob_8Hq2ZtL4mXr9",    "objeto": "cobranca",    "status": "paga",    "valor": 18990,    "moeda": "BRL",    "metodo": "pix",    "pago_em": "2026-10-28T15:00:04Z"  }}

Tabela de eventos

Estes são os eventos mais usados. A lista completa está na referência da API.

Evento	Quando acontece	Objeto
`cobranca.criada`	A cobrança foi criada e aguarda pagamento.	cobranca
`cobranca.paga`	O pagamento foi confirmado pelo banco ou emissor.	cobranca
`cobranca.expirada`	O prazo de pagamento acabou sem pagamento.	cobranca
`cobranca.recusada`	O emissor ou o Radar recusou o pagamento.	cobranca
`estorno.criado`	Um estorno total ou parcial foi solicitado.	estorno
`estorno.concluido`	O dinheiro voltou para o comprador.	estorno
`repasse.agendado`	Um repasse foi programado para a sua conta.	repasse
`repasse.liquidado`	O repasse caiu na conta de destino.	repasse

Assinatura HMAC

Cada requisição traz o cabeçalho Tessela-Signature com um carimbo de tempo e uma assinatura HMAC-SHA256 do corpo. Verifique a assinatura antes de processar o evento e recuse carimbos com mais de 5 minutos.

HTTP

Tessela-Signature: t=1793199604,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Atenção. Use o corpo bruto da requisição para verificar a assinatura. Frameworks que fazem parse do JSON antes mudam os bytes e a verificação falha.

server.js

import { Webhooks } from '@tessela/node'; app.post('/webhooks/tessela', express.raw({ type: 'application/json' }), (req, res) => {  const evento = Webhooks.verify(    req.body,    req.header('Tessela-Signature'),    process.env.TESSELA_WEBHOOK_SECRET,  );   if (evento.tipo === 'cobranca.paga') liberarPedido(evento.dados.id);  res.sendStatus(200);});

Reenvio e idempotência

Se o seu servidor não responder 2xx em 10 segundos, a Tessela reenvia com espera exponencial por até 72 horas: 1 min, 5 min, 30 min, 2 h, 6 h e depois a cada 12 h. O mesmo evento pode chegar mais de uma vez; use o id para ignorar repetições.

Boas práticas

Responda 200 rápido e processe o evento numa fila. Não dependa da ordem de chegada: use o campo criado_em e o status do objeto. Mantenha a URL do webhook atrás de HTTPS.

Perigo. Nunca libere um pedido com base apenas no redirecionamento do checkout. Só o webhook cobranca.paga confirma o pagamento.