Configurando Webhooks

Guia

Atualizado em 25 de março de 2026 · 2 min de leitura

Recente

Receba notificações automáticas sobre eventos de pagamento no seu sistema.

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
`subscription.paid`	Cobrança recorrente aprovada
`subscription.cancelled`	Assinatura cancelada

[!WARNING] Retorne HTTP 200 o mais rápido possível. Processamentos longos devem ser feitos de forma assíncrona (fila/worker). A Dom reenvía o webhook caso não receba resposta em 30 segundos.

Próximos passos

Eventos de Webhook — lista completa de eventos
Verificação de Assinatura — detalhes da validação HMAC

Esta página foi útil?