Configurando Webhooks

Webhooks permitem que sua aplicação receba notificações em tempo real quando eventos acontecem na Dom Pagamentos — pagamentos aprovados, recusados, estornos, entre outros.

[!NOTE] Você vai precisar de uma URL pública acessível pela internet. Para testes locais, use ferramentas como ngrok ou localtunnel.

Crie um endpoint no seu servidor

Implemente uma rota POST que receba o payload do webhook e retorne HTTP 200.

Registre a URL no painel

Acesse **Configurações → Webhooks** no painel Dom e adicione sua URL.

Valide a assinatura

Todo webhook inclui o header `X-Dom-Signature`. Verifique-o para garantir que a requisição veio da Dom.

Processe os eventos

Cada evento tem um campo `type` que identifica o que aconteceu. Trate cada tipo conforme sua lógica de negócio.

Validando a assinatura

import crypto from 'crypto';

function verificarAssinatura(payload, signature, secret) {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return hmac === signature;
}

// No seu handler Express/Next.js:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-dom-signature'];
  const rawBody = JSON.stringify(req.body);

  if (!verificarAssinatura(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Assinatura inválida');
  }

  const { type, data } = req.body;

  switch (type) {
    case 'transaction.paid':
      // processar pagamento aprovado
      break;
    case 'transaction.refused':
      // tratar pagamento recusado
      break;
    case 'transaction.refunded':
      // processar estorno
      break;
  }

  res.status(200).send('OK');
});

Eventos disponíveis

Evento	Descrição
`transaction.paid`	Pagamento aprovado
`transaction.refused`	Pagamento recusado
`transaction.refunded`	Estorno realizado
`transaction.authorized`	Transação autorizada (aguardando captura)
`transaction.chargeback`	Chargeback registrado
`subscription.paid`	Cobrança recorrente aprovada
`subscription.cancelled`	Assinatura cancelada
`subscription.overdue`	Assinatura com cobrança em atraso
`pixout.paid`	Transferência PIX Out confirmada
`pixout.error`	Transferência PIX Out com erro

Política de reenvio

Se o seu endpoint não retornar HTTP 2xx dentro de 30 segundos, a Dom considera a entrega como falha e reenvia o webhook automaticamente. Implemente sempre processamento assíncrono para evitar timeouts.

[!WARNING] Retorne HTTP 200 o mais rápido possível. Processamentos longos devem ser feitos de forma assíncrona (fila, worker ou job queue). Nunca faça chamadas a bancos de dados lentas ou APIs externas antes de responder.

[!TIP] Implemente idempotência no seu handler — o mesmo evento pode ser entregue mais de uma vez. Use o id da transação para evitar processar o mesmo pagamento duas vezes.

Próximos passos

Eventos de Webhook — lista completa de eventos e payloads
Verificação de Assinatura — detalhes da validação HMAC
Configurando Recorrência — eventos de assinatura recorrente