Webhooks

Como funciona

Criar um webhook no portal

Tudo é feito no portal do lojista. Os nomes em negrito são exatamente os que aparecem na tela.

1. 1

   Prepare o endpoint no seu servidor.

   Uma URL pública que aceite POST com corpo JSON e responda em até 10 segundos. Em Produção a URL precisa usar https://; em Sandbox, http:// também é aceito.
2. 2

   Abra a tela de webhooks no portal.

   No portal: Plataforma › Webhook

   No menu lateral do portal do lojista, em Plataforma, clique em Webhook e depois em Novo endpoint, no canto superior direito. O item só aparece para quem tem a permissão de gerenciar webhooks; se ele não aparecer, peça ao administrador da sua conta.
3. 3

   Preencha a seção Endpoint.

   No portal: Novo endpoint › Endpoint

   Informe a URL do endpoint, escolha o Ambiente e, se quiser, uma Descrição de até 200 caracteres; ela vira o nome do webhook na lista. Um webhook de Sandbox só recebe eventos de transações de teste; um de Produção, só eventos reais.
4. 4

   Marque os eventos.

   No portal: Novo endpoint › Eventos & filtros

   Marque cada evento que quer receber. A lista completa, com exemplos, está no catálogo de eventos. Assine só o que a sua integração usa.
5. 5

   Escolha o schema de cada evento.

   No portal: Eventos & filtros › Schema

   Ao marcar um evento aparece o campo Schema, já preenchido com Trivvo V2. Nos 8 eventos de cobrança você pode trocar para Trivvo V1. Leia a opção assim: Trivvo V2 - cobranca.paga (v1.0) é o formato Trivvo V2, na revisão 1.0, para o evento cobranca.paga. Veja qual escolher.

   ✓cobranca.pagaEvento de confirmação de pagamento de uma cobrança

   Schema

   Trivvo V2 - cobranca.paga (v1.0)

   Trivvo V1 - cobranca.paga (v1.0)
6. 6

   Confira o payload e, se precisar, filtre.

   No portal: Eventos & filtros › Pré-visualizar payload

   Pré-visualizar payload aplica o schema ao evento mais recente da sua conta e mostra o corpo que será entregue ao lado do evento original. Em Condição (opcional), uma expressão como ofertaId != null filtra quais eventos são entregues (neste exemplo, só cobranças de ofertas); ela é avaliada sobre o evento original, com os nomes de campo que a pré-visualização mostra. Em branco, todos são entregues.
7. 7

   Salve.

   No portal: Novo endpoint

   Clique em Criar webhook. Se algum evento ficou com o selo Schema pendente, escolha o schema dele antes; o portal não salva sem isso. Você volta para a lista, onde o webhook aparece como Saudável.
8. 8

   Gere e guarde o secret.

   No portal: Webhook › Editar › Rotacionar secret

   Na lista, clique no lápis (Editar) do webhook, depois em Rotacionar secret e em Confirmar rotação. Clique em Copiar e guarde o valor no servidor, por exemplo numa variável de ambiente. Toda entrega traz esse valor no header X-Secret.

   !

   O secret completo aparece uma única vez. Depois de fechar a janela o portal mostra só o identificador mascarado. Perdeu o valor? Rotacione de novo e atualize o servidor: o secret anterior deixa de valer na hora.
9. 9

   Confira a primeira entrega.

   No portal: Webhook › Ver logs

   Faça uma transação no ambiente do webhook. Na lista, o ícone de olho (Ver logs) — ou Ver eventos enviados na edição — mostra cada evento; ao abrir um evento você vê as tentativas, com status, código HTTP, duração, a resposta do seu servidor e o payload enviado. Reprocessar envia o evento de novo.

Escolher o schema: Trivvo V2 ou Trivvo V1

O schema define o formato do corpo entregue. Ele é escolhido por evento, no passo 5, e pode ser trocado a qualquer momento editando o webhook. Não há envelope: os campos ficam no primeiro nível do JSON.

O mesmo evento nos dois formatos

cobranca.paga, a mesma cobrança de R$ 100,00. Troque a aba para comparar.

{
  "schemaVersion": "1.0",
  "processedAt": "2025-03-12T09:30:02Z",
  "eventId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-02-28T12:34:56Z",
  "valorPago": 100,
  "moeda": "BRL",
  "formaPagamento": "cartao_de_credito",
  "ofertaId": null,
  "ofertaNome": null,
  "cliente": {
    "nome": "João da Silva",
    "email": "joao.silva@exemplo.com.br",
    "telefone": "+55 11 99999-8888",
    "numeroDocumento": "12345678909"
  },
  "itens": [
    {
      "descricao": "Assinatura Mensal",
      "valor": 50,
      "quantidade": 2,
      "atributosAdicionais": null
    }
  ]
}

Os campos de cada evento, com tipo e descrição, estão no catálogo de eventos.

Valores monetários vêm em unidade da moeda (R$ 49,90 = 49.9), exceto os campos terminados em Centavos, o valorTotal de pagamento incompleto e de estorno parcial, e o valorParcela das parcelas, que vêm em centavos (R$ 49,90 = 4990). Campos sem valor chegam como null. Novos campos podem ser adicionados: ignore os que não conhecer.

Receber e validar

O seu endpoint confere o secret, guarda o evento e responde rápido. O processamento pesado vai para uma fila.

// Exemplo em Node.js (Express)
const crypto = require('crypto');
const segredo = Buffer.from(process.env.TRIVVO_WEBHOOK_SECRET);

app.post('/webhooks/trivvo', express.json(), (req, res) => {
  const recebido = Buffer.from(req.get('X-Secret') || '');
  if (recebido.length !== segredo.length || !crypto.timingSafeEqual(recebido, segredo)) {
    return res.sendStatus(401);
  }
  const entrega = req.get('X-Request-ID');
  if (jaProcessado(entrega)) return res.sendStatus(200);
  fila.publicar(entrega, req.body);   // processe depois
  res.sendStatus(200);
});

A requisição

Toda entrega é um POST com Content-Type: application/json e os headers abaixo.

Testar antes de ir para produção

1. Crie um webhook com Ambiente Sandbox. A URL pode ser http://, por exemplo um túnel para a sua máquina.
2. Faça uma venda de teste e confira em Ver logs se a tentativa ficou como Sucesso e se o seu servidor gravou o evento.
3. Force um erro (responda 500) e veja a nova tentativa aparecer; depois use Reprocessar.
4. Quando estiver tudo certo, crie um segundo webhook com Ambiente Produção, URL https:// e o seu próprio secret.

Reenvio e desativação

Status das tentativas em Ver logs

Boas práticas

• Responda rápido. Guarde o evento, responda 200 e processe numa fila. Acima de 10 segundos a tentativa conta como falha.
• Deduplique pelo X-Request-ID. Ele é o mesmo em todas as tentativas do mesmo evento; o eventId do payload muda a cada tentativa.
• Não dependa da ordem. Eventos podem chegar fora de ordem: compare o timestamp antes de sobrescrever um status.
• Ignore campos que não conhece. Novos campos podem ser adicionados ao schema sem aviso.
• Separe Sandbox e Produção. Um webhook por ambiente, cada um com o seu secret.
• Rotacione o secret com cuidado. A rotação invalida o valor antigo na hora: atualize o servidor logo em seguida e confira em Ver logs.