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 webhooks segue as especificações do Standard Webhooks, garantindo compatibilidade com as melhores práticas do setor e bibliotecas de webhook existentes.

Principais Recursos

Real-time Delivery

Receba notificações instantâneas quando eventos acontecerem

Secure by Default

Verificação de assinatura HMAC SHA256 inclusa

Automatic Retries

Lógica de tentativa automática com backoff exponencial integrada

Event Filtering

Inscreva-se somente nos eventos que você precisa

Começando

1

Access Webhook Settings

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

Create Webhook Endpoint

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

Add Endpoint URL

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

Select Events to Receive

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

Get Secret Key

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 cliente ou repositórios públicos.
6

Rotate Secret (Optional)

Se necessário, você pode rotacionar seu segredo de webhook para reforçar a segurança. Clique no botão Rotacionar Secret nas configurações do webhook.
Rotacionar o segredo irá expirar o atual e substituí-lo por um novo. O segredo antigo só será válido pelas próximas 24 horas. Depois disso, tentar verificar com o segredo antigo falhará.
Use a rotação de segredos periodicamente ou imediatamente se suspeitar que o 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

Navigate to Webhook Details

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

Select Your Endpoint

Clique no endpoint de webhook que deseja configurar.
3

Open Event Settings

Na página de detalhes do webhook, você verá a seção “Eventos inscritos”. Clique no botão Editar para modificar suas assinaturas de eventos.

Gerenciando Inscrições de Eventos

1

View Available Events

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

Search and Filter

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

Select Events

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

Review Event Details

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

Save Configuration

Clique em Salvar para aplicar suas alterações ou em Cancelar para descartá-las.
Se você desmarcar todos os eventos, seu endpoint de webhook não receberá notificações. Certifique-se de selecionar pelo menos os eventos necessários para o funcionamento adequado da sua aplicação.

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.
Processe webhooks de forma assíncrona reconhecendo o recebimento imediatamente com um código de status 200 e depois tratand 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 reenvio 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 reenviar manualmente mensagens individuais ou recuperar em massa todas as falhas a qualquer momento.

Idempotência

Cada evento de webhook inclui um cabeçalho único webhook-id. Use esse 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...
});
Implemente sempre checagens de idempotência. Devido às 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 payload mais recente 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 e do timestamp do webhook, 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 seu segredo 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 JSON bruta exata payload, separadas por pontos (.).
  2. Calcule o HMAC SHA256 dessa string usando sua chave secreta de webhook do Painel.
  3. Compare a assinatura calculada com o cabeçalho webhook-signature. Se eles coincidirem, o webhook é autêntico.
Seguimos a especificação do Standard Webhooks. Você pode usar as bibliotecas deles para verificar assinaturas: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Para formatos de payload de evento, veja o Webhook Payload.

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á reenviado.

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 assincronamente 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 seu segredo de webhook com segurança usando variáveis de ambiente ou um gerenciador de segredos. Nunca envie segredos para o 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
obrigatório
Identificador único para este evento de webhook. Use-o para checagens de idempotência.
webhook-signature
string
obrigatório
Assinatura HMAC SHA256 para verificar a autenticidade do webhook.
webhook-timestamp
string
obrigatório
Timestamp Unix (em segundos) quando o webhook foi enviado.

Corpo da Solicitação

business_id
string
obrigatório
Seu identificador comercial Dodo Payments.
type
string
obrigatório
Tipo de evento que acionou este webhook (por exemplo, payment.succeeded, subscription.active).
timestamp
string
obrigatório
Timestamp formatado em ISO 8601 de quando o evento ocorreu.
data
object
obrigatório
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

Navigate to Webhooks

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

Select Your Endpoint

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

Open Testing Tab

Clique na aba Teste para acessar a interface de testes de webhook.

Testando Seu Webhook

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

Select Event Type

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

Review Schema and Example

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

Send Test Event

Clique no botão Enviar Exemplo para enviar um webhook de teste ao seu endpoint.
Importante: Mensagens falhas enviadas pela interface de testes não serão reenviadas. Isso serve apenas para testes.

Verificando Seu Teste

1

Check Your Endpoint

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

Verify Signature

Verifique se a validação de assinatura está funcionando corretamente com o payload de teste.
3

Test Response

Confirme se 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.active':
      await handleSubscriptionActive(data);
      break;
    // Add more event handlers...
  }
}
Teste seu manipulador de webhook minuciosamente usando a interface de testes do painel antes de processar eventos de produção. Isso ajuda a identificar e corrigir problemas cedo.

Testando Webhooks com a CLI

O CLI Dodo Payments fornece dois comandos para testar webhooks durante o desenvolvimento local, sem precisar sair do terminal.

Ouvir Webhooks Ao Vivo Localmente

Encaminhe eventos reais de webhook da sua conta em modo de teste para seu servidor local em tempo real:
dodo wh listen
A CLI abre uma conexão WebSocket com a Dodo Payments e encaminha cada evento de webhook para seu endpoint local (por exemplo, http://localhost:3000/webhook), preservando todos os cabeçalhos, incluindo cabeçalhos de assinatura para testes de verificação.
O ouvinte funciona apenas com chaves de API em modo de teste. Execute dodo login e selecione o Modo de Teste antes de usar este comando.

Acionar Eventos de Webhook Mock

Envie payloads simulados de webhook para qualquer endpoint sem criar transações reais:
dodo wh trigger
Esta ferramenta interativa permite que você selecione entre os 22 tipos de eventos suportados e envia payloads simulados realistas para seu endpoint. Ele repete o processo para que você possa testar vários eventos em uma sessão.
Payloads simulados de webhook originados do dodo wh trigger não são assinados. Use unsafe_unwrap() em vez de unwrap() no seu manipulador de webhook apenas durante os testes.

CLI Webhook Testing Docs

Consulte a documentação completa da CLI para testes de webhook

Configurações Avançadas

A aba Configurações Avançadas oferece opções adicionais de configuração 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

Access Rate Limit Settings

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

Configure Rate Limit

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

Set Limits

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

Cabeçalhos Personalizados

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

Add Custom Header

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

Add Multiple Headers

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

Save Configuration

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

Transformações

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

Enable Transformations

Ative a alternância Habilitado para ativar o recurso de transformação.
2

Configure Transformation

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

Test Transformation

Use a interface de testes para verificar se sua transformação funciona corretamente antes de entrar em produção.
Transformações podem afetar significativamente o desempenho da entrega de webhooks. Teste minuciosamente e mantenha a lógica de transformação simples e eficiente.
As 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

Monitoramento de Logs de Webhook

A aba Logs fornece visibilidade abrangente sobre o status de entrega dos seus webhooks, permitindo monitorar, depurar e gerenciar eventos de webhook de forma eficaz.
Logs

Monitoramento de Atividades

A aba Atividades fornece insights em tempo real sobre o desempenho da entrega dos seus webhooks com análises visuais.
Atividades

Alertas por E-mail

Mantenha-se informado sobre a saúde dos seus webhooks com notificações automáticas por e-mail. Quando as entregas de webhooks começarem a falhar ou seu endpoint parar de responder, você receberá alertas por e-mail para que possa agir rapidamente e manter suas integrações funcionando sem problemas.
Configurações de alertas de Webhook mostrando a configuração de notificações por e-mail

Ativar Alertas por E-mail

1

Navigate to Alerting Settings

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

Enable Email Notifications

Ative Notificações por e-mail para começar a receber alertas sobre problemas de entrega de webhooks.
3

Configure Email Address

Insira o endereço de e-mail para o qual você deseja receber alertas de webhook. Enviaremos notificações para esse endereço quando ocorrerem certos eventos relacionados à sua configuração de webhooks, como problemas de entrega que podem afetar suas integrações.
Ative alertas por e-mail para detectar problemas de entrega antecipadamente e manter integrações confiáveis. Você será notificado quando as entregas falharem ou seu endpoint ficar sem resposta.

Implantar em Plataformas em Nuvem

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