Receba notificações em tempo real quando eventos ocorrerem no Dodo Payments. Automatize fluxos de trabalho e mantenha seus sistemas sincronizados com a entrega instantânea de eventos.
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.
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.
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.
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.
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.
Se a entrega de um webhook falhar, o Dodo Payments tenta automaticamente novamente com retrocesso exponencial para evitar sobrecarregar seu sistema.
Tentativa
Atraso
Descrição
1
Imediatamente
A primeira nova tentativa acontece imediatamente
2
5 segundos
Segunda tentativa após um curto atraso
3
5 minutos
Terceira tentativa com aumento de retrocesso
4
30 minutos
Quarta tentativa continuando o retrocesso
5
2 horas
Quinta tentativa com atraso estendido
6
5 horas
Sexta tentativa com atraso maior
7
10 horas
Sétima tentativa com atraso máximo
8
10 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.
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.
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.
Implemente idempotência usando o cabeçalho webhook-id para processar com segurança o mesmo evento várias vezes sem efeitos colaterais.
Proteja sua chave secreta de webhook
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.
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.
Aqui está uma implementação completa do Express.js mostrando verificação e manipulação de webhook:
Copiar
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.
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 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
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.
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.
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.
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.