Pular para o conteúdo principal

GitHub Repository

Código-fonte completo e guia de configuração

Configuração Rápida

1. Pré-requisitos

2. Instalar Dependências

3. Configuração do Banco de Dados

  1. Cadastre-se no Neon
  2. Crie um novo projeto
  3. Abra o Editor SQL
  4. Copie e cole o conteúdo de schema.sql
  5. Execute a consulta
  6. Obtenha sua string de conexão no Neon → Connection Details

4. Definir Variáveis de Ambiente Iniciais

Via Vercel CLI:
Nota: Configuraremos DODO_PAYMENTS_WEBHOOK_KEY após a implantação, assim que você tiver sua URL do webhook.

5. Implantar

6. Obter Sua URL de Webhook

Sua URL de webhook é:

7. Registrar Webhook no Painel do DodoPayments

  1. Vá para DodoPayments Dashboard → Developer → Webhooks
  2. Crie um novo endpoint de webhook
  3. Configure sua URL do webhook como o endpoint
  4. Ative esses eventos de assinatura:
    • subscription.active
    • subscription.cancelled
    • subscription.renewed
  5. Copie o Signing Secret

8. Definir Chave de Webhook e Reimplantar

O Que Ele Faz

Processa eventos de assinatura e os armazena no PostgreSQL:
  • subscription.active - Cria/atualiza registros de clientes e assinaturas
  • subscription.cancelled - Marca a assinatura como cancelada
  • subscription.renewed - Atualiza a próxima data de cobrança

Principais Recursos

Verificação de assinatura - Usando a biblioteca dodopayments
Idempotência - Evita processamento duplicado com IDs de webhook
Registro de eventos - Registro completo de auditoria na tabela webhook_events
Tratamento de erros - Registrado e passível de nova tentativa
Nota: Esta implementação demonstra o tratamento de três eventos principais de assinatura (subscription.active, subscription.cancelled, subscription.renewed) com campos mínimos. Você pode estendê-la facilmente para suportar tipos de eventos adicionais e campos com base em seus requisitos.

Arquivos de Configuração

Esquema do Banco de Dados

Tabelas criadas:
  • customers - Email, nome, dodo_customer_id
  • subscriptions - Status, valor, next_billing_date, vinculado a clientes
  • webhook_events - Registro de eventos com webhook_id para idempotência

Código de Implementação

Como Funciona

O manipulador de webhook:
  1. Desativa o parsing do corpo - Para acessar o corpo bruto para verificação da assinatura
  2. Verifica a assinatura - Garante que a solicitação seja da DodoPayments usando HMAC-SHA256
  3. Verifica duplicatas - Usa o ID do webhook para evitar processar o mesmo evento duas vezes
  4. Registra o evento - Armazena o webhook bruto na tabela webhook_events para trilha de auditoria
  5. Processa o evento - Cria ou atualiza clientes e assinaturas no Neon
  6. Trata erros - Registra falhas e marca o evento como não processado para nova tentativa

Testando

Desenvolvimento local:
Ver logs no Painel do Vercel:
  1. Selecione seu projeto
  2. Vá para Implantações → última implantação
  3. Clique em FunçõesLogs
Configure no Painel do DodoPayments:
  1. Vá para Desenvolvedores → Webhooks
  2. Adicione o endpoint com sua URL de Funções Vercel
  3. Habilite: subscription.active, subscription.cancelled, subscription.renewed

Problemas Comuns

Recursos

Última modificação em 22 de maio de 2026