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. Inscreva-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 do Neon → Detalhes da Conexão

4. Configurar Segredos Iniciais

Nota: Definiremos DODO_PAYMENTS_WEBHOOK_KEY após o deploy quando você tiver sua URL de webhook.

5. Atualizar wrangler.toml

Edite wrangler.toml e defina o nome do seu worker:

6. Implantar

7. Obter Sua URL de Webhook

Sua URL de webhook é:

8. Registrar Webhook no Painel do DodoPayments

  1. Acesse o Painel do DodoPayments → Desenvolvedor → Webhooks
  2. Crie um novo endpoint de webhook
  3. Configure sua URL de webhook como o endpoint
  4. Ative estes eventos de assinatura:
    • subscription.active
    • subscription.cancelled
    • subscription.renewed
  5. Copie o Segredo de Assinatura

9. 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 - Trilha completa 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 adicionais de eventos e campos conforme suas necessidades.

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. Verifica a assinatura - Garante que a solicitação é da DodoPayments usando HMAC-SHA256
  2. Verifica duplicatas - Usa o ID do webhook para evitar processar o mesmo evento duas vezes
  3. Registra o evento - Armazena o webhook bruto na tabela webhook_events para trilha de auditoria
  4. Processa o evento - Cria ou atualiza clientes e assinaturas
  5. Trata erros - Registra falhas e marca o evento como não processado para nova tentativa

Testando

Desenvolvimento local:
Configurar no Painel do DodoPayments:
  1. Vá para Desenvolvedores → Webhooks
  2. Adicione um endpoint com sua URL de Worker
  3. Ative: subscription.active, subscription.cancelled, subscription.renewed

Problemas Comuns

Recursos

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