Webhooks

Pense no webhook como o jeito da troqpay te avisar que alguma coisa mudou. Em vez de perguntar para a API o tempo todo se um checkout foi pago, você cadastra uma URL no seu sistema e a troqpay envia um POST sempre que um evento relevante acontecer.

Por que usar webhooks

Sem webhook, seu backend teria que ficar consultando a API repetidamente para descobrir se o pagamento foi confirmado. Com webhook, a troqpay te avisa assim que isso acontecer. Na prática, isso ajuda você a:

atualizar o status de um pedido
liberar acesso a um produto
registrar a confirmação do pagamento
reduzir polling desnecessário

Onde cadastrar no app

No fluxo mais comum, você faz isso no app da troqpay:

Abra a área de integração

Entre no app e vá até a área de integração da sua conta.

Cadastre a URL do endpoint

Informe a URL pública que vai receber os eventos da troqpay.

Guarde o segredo do webhook

Você vai usar esse segredo para validar o header x-troqpay-signature.

Teste no sandbox antes de subir para produção

Valide o endpoint com eventos de teste antes de trocar a chave e a URL final.

Como funciona na prática

Você cria um endpoint no seu sistema

Exemplo: https://seusistema.com/webhooks/troqpay

Você cadastra essa URL na sua conta

A troqpay passa a enviar eventos para esse endpoint.

Seu servidor recebe o evento

O corpo do POST informa o tipo do evento e os dados do checkout.

Seu sistema processa e responde 2xx

Depois disso, seu fluxo segue normalmente no seu sistema.

O que a troqpay espera do seu endpoint

Receba JSON por HTTPS

Seu endpoint precisa aceitar POST com corpo JSON e estar disponível publicamente por HTTPS.

Valide a assinatura

Use x-troqpay-signature e o segredo do webhook para confiar no evento.

Responda 2xx rápido

Faça o ack assim que a entrega for aceita. Deixe processamento pesado para sua fila interna.

Espere reentregas

Trate o modelo de entrega como at least once: o mesmo evento pode chegar mais de uma vez.

Eventos disponíveis hoje

Evento	Quando acontece
`checkout.created`	Quando o checkout é criado com sucesso
`checkout.paid`	Quando o pagamento Pix é confirmado
`checkout.expired`	Quando o checkout expira sem pagamento

Ordem, timeout e reentregas

para o mesmo checkout, o fluxo esperado costuma ser checkout.created seguido de checkout.paid ou checkout.expired
não assuma ordem estrita entre eventos de checkouts diferentes
a troqpay tenta entregar até 5 vezes com backoff 60s → 5m → 15m → 60m
o timeout de cada tentativa é de 5 segundos
se o seu endpoint não responder 2xx dentro desse prazo, a entrega é retentada
guarde event.id para garantir processamento idempotente — o mesmo evt_... pode chegar mais de uma vez

Restrições do endpoint

A troqpay valida algumas coisas quando você cadastra a URL no app:

precisa ser uma URL absoluta válida
precisa usar http:// ou https://
não pode ter credenciais embutidas (https://user:pass@host/... é rejeitado)
em produção (trq_live_), precisa ser https:// e não pode ser endereço local ou de rede privada (RFC 1918, loopback, link-local)

O entregador da troqpay não segue redirects. Se o seu endpoint responder 301, 302, 307 ou 308, a entrega é considerada falha e consome uma das 5 tentativas. Cadastre sempre a URL final (sem redirect na frente, mesmo que via CDN).

Exemplo de payload

{
  "id": "evt_4a8b3c1d5e6f2a9b0c1d2e3f",
  "type": "checkout.paid",
  "createdAt": "2026-04-25T14:02:10.000Z",
  "livemode": false,
  "data": {
    "checkout": {
      "id": "chk_4a8b3c1d5e6f2a9b0c1d",
      "livemode": false,
      "status": "PAID",
      "amount": 12990,
      "currency": "BRL",
      "description": "Plano Pro",
      "externalId": "order_1001",
      "checkoutUrl": "https://pay.troqpay.com/pay/chk_4a8b3c1d5e6f2a9b0c1d",
      "createdAt": "2026-04-25T14:00:00.000Z",
      "expiresAt": "2026-04-25T14:30:00.000Z",
      "paidAt": "2026-04-25T14:02:10.000Z",
      "customer": {
        "name": "Maria Silva",
        "email": "maria@example.com",
        "document": null
      },
      "pix": {
        "copyPaste": "00020101021226840014br.gov.bcb.pix...",
        "qrCodeUrl": "https://api.troqpay.com/qrcode/chk_4a8b3c1d5e6f2a9b0c1d.png"
      },
      "settlement": {
        "currency": "BRL",
        "status": "AVAILABLE",
        "amount": "129.90"
      },
      "metadata": {
        "plan": "pro"
      }
    }
  }
}

data.checkout é exatamente a mesma forma retornada por GET /v1/checkouts/{checkoutId}. Inclui customer (sem phone), pix, settlement e metadata.

Assinatura

Cada endpoint cadastrado no app tem o seu próprio segredo de assinatura, mostrado uma vez no momento do cadastro. Toda entrega inclui o header:

x-troqpay-signature

O valor é HMAC-SHA256 do corpo bruto da requisição, codificado em hex, usando esse segredo. Em pseudo-fórmula:

x-troqpay-signature = HMAC_SHA256(rawBody, signingSecret).hex()

Compare a assinatura calculada do seu lado com o header recebido antes de processar o evento.

Exemplo de verificação em Node.js

import crypto from "node:crypto";

const signature = request.headers["x-troqpay-signature"];
const rawBody = request.rawBody; // os bytes exatos recebidos, antes de qualquer parser

const expected = crypto
  .createHmac("sha256", process.env.TROQPAY_WEBHOOK_SIGNING_SECRET)
  .update(rawBody)
  .digest("hex");

if (signature !== expected) {
  throw new Error("Invalid signature");
}

O segredo é único por endpoint cadastrado. Se você tem mais de um endpoint na mesma conta, cada um tem o seu segredo próprio.

O que responder para a troqpay

Resposta do endpoint	O que isso significa
`2xx`	A entrega foi aceita pelo seu sistema
`4xx` ou `5xx`	A entrega falhou e seu endpoint precisa ser investigado
Timeout	Trate como falha de entrega e prepare seu endpoint para reprocessar o evento

Boas práticas de processamento

Responda 2xx rápido

Faça o ack da entrega rapidamente e deixe o processamento pesado para sua fila interna.

Use idempotência

Guarde event.id para garantir que a mesma entrega não seja processada duas vezes.

Espere reentregas

Retry faz parte da vida de qualquer integração séria. Seu endpoint precisa lidar bem com isso.

Logue com contexto

Registre event.id, checkout.id, externalId e livemode para investigar problemas sem dor.

Use livemode para separar eventos de teste e produção no seu pipeline.

O campo customer.phone aceito no envio do checkout não é retornado dentro de data.checkout.customer. Se você precisa do telefone para conciliação, salve-o do seu lado quando criar o checkout.

Próximos passos

Modelar os checkouts Pix
Subir para produção
Abra a aba API Reference para consultar a referência completa dos eventos e recursos

Precisa de ajuda para seguir?

Voltar ao Quickstart

Se você ainda não criou a primeira cobrança, volte e valide o fluxo completo.

Revisar erros

Veja como investigar falhas de autenticação, payload ou resposta do endpoint.

Abrir o app

Use o app da troqpay para revisar suas URLs, chaves e o ambiente que você está usando.

Comece aqui

Documentation Index

​Webhooks

​Por que usar webhooks

​Onde cadastrar no app

​Como funciona na prática

​O que a troqpay espera do seu endpoint

Receba JSON por HTTPS

Valide a assinatura

Responda 2xx rápido

Espere reentregas

​Eventos disponíveis hoje

​Ordem, timeout e reentregas

​Restrições do endpoint

​Exemplo de payload

​Assinatura

​Exemplo de verificação em Node.js

​O que responder para a troqpay

​Boas práticas de processamento

Responda 2xx rápido

Use idempotência

Espere reentregas

Logue com contexto

​Próximos passos

​Precisa de ajuda para seguir?

Voltar ao Quickstart

Revisar erros

Abrir o app

Webhooks

Por que usar webhooks

Onde cadastrar no app

Como funciona na prática

O que a troqpay espera do seu endpoint

Eventos disponíveis hoje

Ordem, timeout e reentregas

Restrições do endpoint

Exemplo de payload

Assinatura

Exemplo de verificação em Node.js

O que responder para a troqpay

Boas práticas de processamento

Próximos passos

Precisa de ajuda para seguir?