Skip to main content

​
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

​
Como funciona na prática

1

Você cria um endpoint no seu sistema

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

Você cadastra essa URL na sua conta

A troqpay passa a enviar eventos para esse endpoint.
3

Seu servidor recebe o evento

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

Seu sistema processa e responde 2xx

Depois disso, seu fluxo segue normalmente no seu sistema.

​
Eventos disponíveis hoje

EventoQuando acontece
checkout.createdQuando o checkout é criado com sucesso
checkout.paidQuando o pagamento Pix é confirmado
checkout.expiredQuando o checkout expira sem pagamento

​
Exemplo de payload

{
  "id": "evt_01HR7PB4Q4G33AYM1V7BTRC0FC",
  "type": "checkout.paid",
  "createdAt": "2026-03-28T14:02:10.000Z",
  "livemode": false,
  "data": {
    "checkout": {
      "id": "chk_01HR7P8Z5N7A8Q2P8Y7F2D8Q6J",
      "status": "PAID",
      "externalId": "order_1001"
    }
  }
}

​
Assinatura

Toda entrega inclui uma assinatura no header: 
x-troqpay-signature
Valide essa assinatura antes de confiar no evento.

​
Exemplo de verificação em Node.js

import crypto from "node:crypto";

const signature = request.headers["x-troqpay-signature"];
const rawBody = request.rawBody;

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

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

​
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.

​
Próximos passos