Pular para o conteúdo principal
Imagem de Capa do Webhook
Webhooks fornecem notificações em tempo real quando eventos específicos ocorrem em sua conta Dodo Payments. Use webhooks para automatizar fluxos de trabalho, atualizar seu banco de dados, enviar notificações e manter seus sistemas sincronizados.
Nossa implementação de webhook segue a especificação Standard Webhooks, garantindo compatibilidade com as melhores práticas do setor e bibliotecas de webhook existentes.

Principais Recursos

Entrega em Tempo Real

Receba notificações instantâneas quando eventos ocorrerem

Seguro por Padrão

Verificação de assinatura HMAC SHA256 incluída

Tentativas Automáticas

Lógica de nova tentativa embutida com retrocesso exponencial

Filtragem de Eventos

Inscreva-se apenas nos eventos que você precisa

Começando

1

Acessar Configurações de Webhook

Navegue até o Painel DodoPayments e vá para Settings > Webhooks.
2

Criar Endpoint de Webhook

Clique em Add Webhook para criar um novo endpoint de webhook.
Adicionar Webhook
3

Adicionar URL do Endpoint

Insira a URL onde você deseja receber eventos de webhook.
4

Selecionar Eventos a Receber

Escolha os eventos específicos que seu endpoint de webhook deve escutar selecionando-os na lista de eventos.
Apenas os eventos selecionados acionarão webhooks para seu endpoint, ajudando você a evitar tráfego e processamento desnecessários.
5

Obter Chave Secreta

Obtenha seu Secret Key de webhook na página de configurações. Você usará isso para verificar a autenticidade dos webhooks recebidos.
Mantenha sua chave secreta de webhook segura e nunca a exponha em código do lado do cliente ou repositórios públicos.
6

Rotacionar Segredo (Opcional)

Se necessário, você pode rotacionar seu segredo de webhook para maior segurança. Clique no botão Rotacionar Segredo nas configurações do seu webhook.
Rotacionar o segredo expirará e substituirá por um novo. O antigo só será válido pelas próximas 24 horas. Depois disso, tentar verificar com o antigo falhará.
Use a rotação de segredos periodicamente ou imediatamente se suspeitar que seu segredo atual foi comprometido.

Configurando Eventos Inscritos

Você pode configurar quais eventos específicos deseja receber para cada endpoint de webhook.

Acessando a Configuração de Eventos

1

Navegar até os Detalhes do Webhook

Vá para o seu Painel Dodo Payments e navegue até Settings > Webhooks.
2

Selecionar Seu Endpoint

Clique no endpoint de webhook que você deseja configurar.
3

Abrir Configurações de Evento

Na página de detalhes do webhook, você verá uma seção “Eventos Inscritos”. Clique no botão Editar para modificar suas inscrições de eventos.

Gerenciando Inscrições de Eventos

1

Ver Eventos Disponíveis

A interface exibe todos os eventos de webhook disponíveis organizados em uma estrutura hierárquica. Os eventos são agrupados por categoria (por exemplo, dispute, payment, subscription).
2

Pesquisar e Filtrar

Use a barra de pesquisa para encontrar rapidamente eventos específicos digitando nomes de eventos ou palavras-chave.
3

Selecionar Eventos

Marque as caixas ao lado dos eventos que você deseja receber. Você pode:
  • Selecionar sub-eventos individuais (por exemplo, dispute.accepted, dispute.challenged)
  • Selecionar eventos pai para receber todos os sub-eventos relacionados
  • Misturar e combinar eventos específicos com base em suas necessidades
4

Revisar Detalhes do Evento

Passe o mouse sobre o ícone de informação (ⓘ) ao lado de cada evento para ver uma descrição de quando esse evento é acionado.
5

Salvar Configuração

Clique em Salvar para aplicar suas alterações ou Cancelar para descartar modificações.
Se você desmarcar todos os eventos, seu endpoint de webhook não receberá nenhuma notificação. Certifique-se de selecionar pelo menos os eventos que seu aplicativo precisa para funcionar corretamente.

Entrega de Webhook

Timeouts

Webhooks têm uma janela de timeout de 15 segundos para operações de conexão e leitura. Certifique-se de que seu endpoint responda rapidamente para evitar timeouts.
Processar webhooks de forma assíncrona reconhecendo o recebimento imediatamente com um código de status 200, e depois lidando com o processamento real em segundo plano.

Tentativas Automáticas

Se a entrega de um webhook falhar, o Dodo Payments tenta automaticamente novamente com retrocesso exponencial para evitar sobrecarregar seu sistema.
TentativaAtrasoDescrição
1ImediatamenteA primeira nova tentativa acontece imediatamente
25 segundosSegunda tentativa após um curto atraso
35 minutosTerceira tentativa com aumento de retrocesso
430 minutosQuarta tentativa continuando o retrocesso
52 horasQuinta tentativa com atraso estendido
65 horasSexta tentativa com atraso maior
710 horasSétima tentativa com atraso máximo
810 horasÚltima tentativa - webhook marcado como falhado se não for bem-sucedido
Máximo de 8 tentativas de nova tentativa por evento de webhook. Por exemplo, se um webhook falhar três vezes antes de ter sucesso, o tempo total de entrega é de aproximadamente 35 minutos e 5 segundos desde a primeira tentativa.
Use o painel Dodo Payments para tentar manualmente mensagens individuais ou recuperar em massa todas as mensagens falhadas a qualquer momento.

Idempotência

Cada evento de webhook inclui um cabeçalho único webhook-id. Use este identificador para implementar idempotência e evitar processamento duplicado.
// Example: Storing webhook IDs to prevent duplicate processing
const processedWebhooks = new Set();

app.post('/webhook', (req, res) => {
  const webhookId = req.headers['webhook-id'];
  
  if (processedWebhooks.has(webhookId)) {
    return res.status(200).json({ received: true });
  }
  
  processedWebhooks.add(webhookId);
  // Process the webhook...
});
Sempre implemente verificações de idempotência. Devido a novas tentativas, você pode receber o mesmo evento várias vezes.

Ordenação de Eventos

Eventos de webhook podem chegar fora de ordem devido a novas tentativas ou condições de rede. Projete seu sistema para lidar com eventos em qualquer sequência.
Você receberá o último payload no momento da entrega, independentemente de quando o evento de webhook foi originalmente emitido.

Protegendo Webhooks

Para garantir a segurança de seus webhooks, sempre valide os payloads e use HTTPS.

Verificando Assinaturas

Cada solicitação de webhook inclui um cabeçalho webhook-signature, uma assinatura HMAC SHA256 do payload do webhook e timestamp, assinada com sua chave secreta.

Verificação de SDK (recomendada)

Todos os SDKs oficiais incluem helpers embutidos para validar e analisar com segurança os webhooks recebidos. Duas métodos estão disponíveis:
  • unwrap(): Verifica assinaturas usando sua chave secreta de webhook
  • unsafe_unwrap(): Analisa payloads sem verificação
Forneça sua chave secreta de webhook via DODO_PAYMENTS_WEBHOOK_KEY ao inicializar o cliente Dodo Payments.
import DodoPayments from 'dodopayments';
import express from 'express';

const app = express();
app.use(express.raw({ type: 'application/json' }));

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
});

app.post('/webhook', async (req, res) => {
  try {
    const unwrapped = client.webhooks.unwrap(req.body.toString(), {
      headers: {
        'webhook-id': req.headers['webhook-id'] as string,
        'webhook-signature': req.headers['webhook-signature'] as string,
        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
      },
    });
    res.json({ received: true });
  } catch (error) {
    res.status(401).json({ error: 'Invalid signature' });
  }
});

Verificação Manual (alternativa)

Se você não estiver usando um SDK, pode verificar assinaturas você mesmo seguindo a especificação Standard Webhooks:
  1. Construa a mensagem assinada concatenando webhook-id, webhook-timestamp, e a string exata payload, separadas por pontos (.).
  2. Calcule o HMAC SHA256 dessa string usando sua chave secreta de webhook do Painel.
  3. Compare a assinatura computada com o cabeçalho webhook-signature. Se corresponderem, o webhook é autêntico.
Seguimos a especificação Standard Webhooks. Você pode usar suas bibliotecas para verificar assinaturas: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Para formatos de payload de eventos, veja o Payload do Webhook.

Respondendo a Webhooks

  • Seu manipulador de webhook deve retornar um 2xx status code para reconhecer o recebimento do evento.
  • Qualquer outra resposta será tratada como uma falha, e o webhook será tentado novamente.

Melhores Práticas

Sempre use URLs HTTPS para endpoints de webhook. Endpoints HTTP são vulneráveis a ataques man-in-the-middle e expõem seus dados de webhook.
Retorne um código de status 200 imediatamente ao receber o webhook. Processe o evento de forma assíncrona para evitar timeouts.
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
Implemente idempotência usando o cabeçalho webhook-id para processar com segurança o mesmo evento várias vezes sem efeitos colaterais.
Armazene sua chave secreta de webhook com segurança usando variáveis de ambiente ou um gerenciador de segredos. Nunca comite segredos no controle de versão.

Estrutura do Payload do Webhook

Entender a estrutura do payload do webhook ajuda você a analisar e processar eventos corretamente.

Formato da Solicitação

POST /your-webhook-url
Content-Type: application/json

Cabeçalhos

webhook-id
string
required
Identificador único para este evento de webhook. Use isso para verificações de idempotência.
webhook-signature
string
required
Assinatura HMAC SHA256 para verificar a autenticidade do webhook.
webhook-timestamp
string
required
Timestamp Unix (em segundos) quando o webhook foi enviado.

Corpo da Solicitação

business_id
string
required
Seu identificador de negócio Dodo Payments.
type
string
required
Tipo de evento que acionou este webhook (por exemplo, payment.succeeded, subscription.created).
timestamp
string
required
Timestamp formatado em ISO 8601 de quando o evento ocorreu.
data
object
required
Payload específico do evento contendo informações detalhadas sobre o evento.

Exemplo de Payload

{
  "business_id": "string",
  "type": "payment.succeeded | payment.failed |...",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "payload_type": "Payment | Subscription | Refund | Dispute | LicenseKey",
    // ... event-specific fields (see below)
  }
}

Testando Webhooks

Você pode testar sua integração de webhook diretamente do painel Dodo Payments para garantir que seu endpoint esteja funcionando corretamente antes de entrar em produção.
Detalhes do Endpoint

Acessando a Interface de Teste

1

Navegar até Webhooks

Vá para o seu Painel Dodo Payments e navegue até Settings > Webhooks.
2

Selecionar Seu Endpoint

Clique no seu endpoint de webhook para acessar sua página de detalhes.
3

Abrir Aba de Testes

Clique na aba Testes para acessar a interface de teste de webhook.

Testando Seu Webhook

A interface de teste fornece uma maneira abrangente de testar seu endpoint de webhook:
1

Selecionar Tipo de Evento

Use o menu suspenso para selecionar o tipo específico de evento que você deseja testar (por exemplo, payment.succeeded, payment.failed, etc.).
O menu suspenso contém todos os tipos de eventos de webhook disponíveis que seu endpoint pode receber.
2

Revisar Esquema e Exemplo

A interface exibe tanto o Esquema (estrutura de dados) quanto o Exemplo (payload de amostra) para o tipo de evento selecionado.
3

Enviar Evento de Teste

Clique no botão Enviar Exemplo para enviar um webhook de teste para seu endpoint.
Importante: Mensagens falhadas enviadas através da interface de teste não serão tentadas novamente. Isso é apenas para fins de teste.

Verificando Seu Teste

1

Verifique Seu Endpoint

Monitore os logs do seu endpoint de webhook para confirmar que o evento de teste foi recebido.
2

Verificar Assinatura

Certifique-se de que sua verificação de assinatura esteja funcionando corretamente com o payload de teste.
3

Testar Resposta

Confirme que seu endpoint retorna um código de status 2xx para reconhecer o recebimento.

Exemplo de Implementação

Aqui está uma implementação completa do Express.js mostrando verificação e manipulação de webhook:
import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
app.use(express.json());

const webhook = new Webhook(process.env.DODO_WEBHOOK_SECRET);

app.post('/webhook/dodo-payments', async (req, res) => {
  try {
    // Extract webhook headers
    const webhookHeaders = {
      "webhook-id": req.headers["webhook-id"] as string,
      "webhook-signature": req.headers["webhook-signature"] as string,
      "webhook-timestamp": req.headers["webhook-timestamp"] as string,
    };

    // Verify the webhook signature
    const payload = JSON.stringify(req.body);
    await webhook.verify(payload, webhookHeaders);
    
    // Acknowledge receipt immediately
    res.status(200).json({ received: true });
    
    // Process webhook asynchronously
    processWebhookAsync(req.body).catch(console.error);
    
  } catch (error) {
    console.error('Webhook verification failed:', error);
    res.status(400).json({ error: 'Invalid signature' });
  }
});

async function processWebhookAsync(data: any) {
  // Handle the webhook event based on type
  switch (data.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(data);
      break;
    case 'subscription.created':
      await handleSubscriptionCreated(data);
      break;
    // Add more event handlers...
  }
}
Teste seu manipulador de webhook minuciosamente usando a interface de teste do painel antes de processar eventos de produção. Isso ajuda a identificar e corrigir problemas cedo.

Configurações Avançadas

A aba Configurações Avançadas fornece opções de configuração adicionais para ajustar o comportamento do seu endpoint de webhook.

Limitação de Taxa (Throttling)

Controle a taxa na qual os eventos de webhook são entregues ao seu endpoint para evitar sobrecarregar seu sistema.
1

Acessar Configurações de Limite de Taxa

Na aba Avançado, localize a seção “Limite de Taxa (throttling)”.
2

Configurar Limite de Taxa

Clique no botão Editar para modificar as configurações de limite de taxa.
Por padrão, os webhooks têm “Sem limite de taxa” aplicado, o que significa que os eventos são entregues assim que ocorrem.
3

Definir Limites

Configure seu limite de taxa desejado para controlar a frequência de entrega de webhook e evitar sobrecarga do sistema.
Use limitação de taxa quando seu manipulador de webhook precisar de tempo para processar eventos ou quando você quiser agrupar vários eventos juntos.

Cabeçalhos Personalizados

Adicione cabeçalhos HTTP personalizados a todas as solicitações de webhook enviadas ao seu endpoint. Isso é útil para autenticação, roteamento ou adição de metadados às suas solicitações de webhook.
1

Adicionar Cabeçalho Personalizado

Na seção “Cabeçalhos Personalizados”, insira uma Chave e Valor para seu cabeçalho personalizado.
2

Adicionar Múltiplos Cabeçalhos

Clique no botão + para adicionar cabeçalhos personalizados adicionais conforme necessário.
3

Salvar Configuração

Seus cabeçalhos personalizados serão incluídos em todas as solicitações de webhook para este endpoint.

Transformações

Transformações permitem que você modifique o payload de um webhook e redirecione-o para uma URL diferente. Este recurso poderoso permite que você:
  • Modifique a estrutura do payload antes do processamento
  • Roteie webhooks para diferentes endpoints com base no conteúdo
  • Adicione ou remova campos do payload
  • Transforme formatos de dados
1

Ativar Transformações

Ative o interruptor Ativado para ativar o recurso de transformação.
2

Configurar Transformação

Clique em Editar transformação para definir suas regras de transformação.
Você pode usar JavaScript para transformar o payload do webhook e especificar uma URL de destino diferente.
3

Testar Transformação

Use a interface de teste para verificar se sua transformação funciona corretamente antes de entrar em produção.
Transformações podem impactar significativamente o desempenho da entrega de webhook. Teste minuciosamente e mantenha a lógica de transformação simples e eficiente.
Transformações são particularmente úteis para:
  • Converter entre diferentes formatos de dados
  • Filtrar eventos com base em critérios específicos
  • Adicionar campos computados ao payload
  • Roteamento de eventos para diferentes microsserviços

Monitorando Logs de Webhook

A aba Logs fornece visibilidade abrangente sobre o status de entrega do seu webhook, permitindo que você monitore, depure e gerencie eventos de webhook de forma eficaz.
Logs

Monitoramento de Atividade

A aba Atividade fornece insights em tempo real sobre o desempenho de entrega do seu webhook com análises visuais.
Atividade

Alertas por Email

Mantenha-se informado sobre a saúde do seu webhook com notificações automáticas por email. Quando as entregas de webhook começam a falhar ou seu endpoint para de responder, você receberá alertas por email para que possa resolver rapidamente os problemas e manter suas integrações funcionando sem problemas.
Configurações de Alerta de Webhook mostrando configuração de notificações por email

Ativar Alertas por Email

1

Navegar até Configurações de Alerta

Vá para o seu Painel Dodo Payments e navegue até Painel → Webhooks → Alertas.
2

Ativar Notificações por Email

Ative Notificações por email para começar a receber alertas sobre problemas de entrega de webhook.
3

Configurar Endereço de Email

Insira o endereço de email onde você deseja receber alertas de webhook. Enviaremos notificações para este endereço quando certos eventos ocorrerem com sua configuração de webhooks, como problemas de entrega que podem afetar suas integrações.
Ative alertas por email para detectar problemas de entrega de webhook cedo e manter integrações confiáveis. Você será notificado quando as entregas falharem ou seu endpoint se tornar não responsivo.

Implantar em Plataformas de Nuvem

Pronto para implantar seu manipulador de webhook em produção? Fornecemos guias específicas para plataformas para ajudá-lo a implantar webhooks em provedores de nuvem populares com as melhores práticas para cada plataforma.
Cada guia de plataforma inclui configuração de ambiente, verificação de assinatura e etapas de implantação específicas para esse provedor.