Receive real-time notifications when events occur in Dodo Payments. Automate workflows and keep your systems synchronized with instant event delivery.
Webhooks provide real-time notifications when specific events occur in your Dodo Payments account. Use webhooks to automate workflows, update your database, send notifications, and keep your systems synchronized.
Our webhook implementation follows the Standard Webhooks specification, ensuring compatibility with industry best practices and existing webhook libraries.
O portal de webhooks do Dodo Payments foi reconstruído com uma experiência de dashboard nativa. Seus endpoints existentes, signing secrets, signature verification, nomes de eventos e payloads de webhook permanecem inalterados. Nenhum trabalho de integração é necessário.
Onde encontrar cada recurso.
Em Developer → Webhooks — as abas Endpoints, Event catalog, Logs, Activity e Settings.
Em um endpoint individual — a aba Overview, com estatísticas de entrega, o signing secret e o Replay history, além das abas Testing e Advanced e das ações de replay em massa.
Em uma mensagem — aberta pela aba Logs, onde cada tentativa de entrega pode ser reproduzida individualmente sem abrir o endpoint.
1
Access Webhook Settings
Acesse o Dodo Payments Dashboard e vá para Developer → Webhooks.
2
Create Webhook Endpoint
Clique em Add endpoint para abrir o painel lateral de criação de endpoint.
3
Enter Endpoint URL or Choose Integration
Insira a URL na qual deseja receber eventos de webhook ou selecione um conector de integração para encaminhar eventos a um serviço de terceiros (Slack, Discord, Zapier, Resend etc.).
4
Select Events to Receive
Escolha os eventos específicos que seu endpoint deve acompanhar. Os eventos são organizados em uma árvore pesquisável, agrupada por recurso. Você pode selecionar eventos individuais ou um recurso pai para receber todos os eventos relacionados.
Somente os eventos selecionados acionarão webhooks para seu endpoint, ajudando a evitar tráfego e processamento desnecessários.
5
Create Endpoint
Clique em Create endpoint para salvar sua configuração.
6
Get Secret Key
Seu webhook signing secret é exibido na aba Overview do endpoint. Você o usará para verificar a autenticidade dos webhooks recebidos.
Mantenha sua webhook secret key segura e nunca a exponha em código do lado do cliente ou repositórios públicos.
7
Rotate Secret (Optional)
Se necessário, você pode fazer a rotação do webhook secret para aumentar a segurança. Clique em Rotate secret, ao lado do secret na aba Overview.
A rotação do secret fará com que ele expire e o substituirá por um novo. O secret antigo só será válido pelas próximas 24 horas. Depois disso, a tentativa de verificação com o secret antigo falhará.
Faça a rotação do secret periodicamente ou imediatamente se suspeitar que o secret atual foi comprometido.
Em vez de criar seu próprio receptor de webhook, você pode encaminhar eventos de webhook diretamente para serviços de terceiros usando conectores de integração. Isso elimina a necessidade de escrever e manter handlers de webhook personalizados para plataformas populares.
Um conector aplica uma transformação que converte o evento do Dodo Payments para o formato esperado pelo destino. Os detalhes fornecidos dependem do destino:
Tipo de conector
O que você fornece
Destinos
Incoming webhook URL
Uma URL de webhook criada no próprio dashboard do fornecedor. Nenhuma API key.
O seletor de conectores no dashboard mostra o conjunto completo atualmente disponível para sua empresa. Portanto, considere a tabela acima como os destinos com instruções de configuração passo a passo, não como uma lista exaustiva. Consulte External Integrations para saber o que cada destino pode fazer quando os eventos chegam até ele.
Escolha um conector ao criar ou editar um endpoint, e o painel lateral exibirá instruções de configuração específicas para esse destino — por exemplo, como criar uma incoming webhook URL no Slack ou onde encontrar sua Resend API key. Antes de salvar, execute o teste de transformação do conector para confirmar que o evento é convertido corretamente para o destino.
Use um conector para alcançar um destino compatível sem escrever código. Se precisar de lógica personalizada, use um endpoint padrão com uma transformation.
Você pode configurar quais eventos específicos cada endpoint de webhook deve receber.
1
Navigate to Webhook Endpoints
Acesse o Dodo Payments Dashboard e vá para Developer → Webhooks.
2
Select Your Endpoint
Clique no endpoint de webhook que deseja configurar.
3
Open Event Configuration
Clique em Edit para abrir o painel lateral de configuração do endpoint.
4
Browse Event Types
O seletor de tipos de evento exibe todos os eventos de webhook disponíveis em uma árvore pesquisável, agrupada por recurso (por exemplo, payment, subscription, dispute). Use a barra de pesquisa para encontrar rapidamente eventos específicos por nome ou palavra-chave.
5
Select Events
Marque as caixas ao lado dos eventos que deseja receber. Você pode:
Selecionar eventos individuais (por exemplo, payment.succeeded, payment.failed)
Selecionar um recurso pai para receber todos os eventos relacionados
Combinar eventos específicos de acordo com suas necessidades
6
Save Configuration
Clique em Save para aplicar suas alterações ou em Cancel para descartá-las.
Se você desmarcar todos os eventos, seu endpoint de webhook não receberá nenhuma notificação. Selecione pelo menos os eventos necessários para que sua aplicação funcione corretamente.
Acesse Developer → Webhooks e abra a aba Event catalog. Ela lista todos os tipos de evento que o Dodo Payments pode enviar, para que você veja o que está disponível antes de inscrever um endpoint. Selecione um evento para visualizar seu schema e um payload de exemplo — a maneira mais rápida de verificar o formato de um campo que você pretende ler.
Webhook Events Guide
Consulte os mesmos eventos como documentação de referência, agrupados por recurso.
Os webhooks têm uma janela de timeout de 15 segundos para as operações de conexão e leitura. Garanta que seu endpoint responda rapidamente para evitar timeouts.
Processe os webhooks de forma assíncrona, confirmando o recebimento imediatamente com um código de status 200 e realizando o processamento efetivo em segundo plano.
Se uma entrega de webhook falhar, o Dodo Payments fará novas tentativas automaticamente com exponential backoff para evitar sobrecarregar seu sistema.
Tentativa
Atraso
Descrição
1
Imediatamente
A primeira tentativa ocorre imediatamente
2
5 segundos
Segunda tentativa após um breve atraso
3
5 minutos
Terceira tentativa com backoff aumentado
4
30 minutos
Quarta tentativa, continuando o backoff
5
2 horas
Quinta tentativa com atraso ampliado
6
5 horas
Sexta tentativa com atraso maior
7
10 horas
Sétima tentativa com atraso máximo
8
10 horas
Tentativa final — o webhook será marcado como falho se não for bem-sucedido
Máximo de 8 tentativas de retry por evento de webhook. Por exemplo, se um webhook falhar três vezes antes de ser concluído com sucesso, o tempo total de entrega será de aproximadamente 35 minutos e 5 segundos desde a primeira tentativa.
Use o dashboard do Dodo Payments para repetir manualmente mensagens individuais ou recuperar em massa todas as mensagens falhas a qualquer momento.
Os eventos de webhook podem chegar fora de ordem devido a retries 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 emitido originalmente.
Cada solicitação de webhook inclui um header webhook-signature, uma assinatura HMAC SHA256 do payload e do timestamp do webhook, assinada com sua secret key.
A verificação de assinatura é a forma compatível de autenticar um webhook. Ela comprova que a solicitação foi assinada com o segredo do seu webhook, algo que uma verificação no nível da rede não pode fazer.As entregas de webhook são enviadas de um conjunto de endereços IP de origem pertencentes à nossa infraestrutura de entrega. Esse conjunto muda de tempos em tempos; portanto, trate os endereços como um detalhe operacional, e não como uma propriedade fixa da integração.
Não use uma allowlist de IPs de origem como mecanismo de autenticação. Uma allowlist mostra apenas de onde veio uma solicitação, não que ela é genuína ou não foi modificada — verifique o cabeçalho webhook-signature em todas as solicitações, conforme descrito em Verificação de assinaturas.
Se sua infraestrutura estiver atrás de um firewall que exige uma allowlist explícita, considere o seguinte:
Não codifique os endereços permanentemente. Os intervalos são adicionados e desativados ao longo do tempo, e uma regra obsoleta bloqueia as entregas silenciosamente.
Solicite os intervalos atuais a support@dodopayments.com antes de restringir um firewall, para trabalhar com uma lista atualizada.
Fique atento aos avisos de alterações. Quando os endereços de entrega mudam, notificamos os merchants afetados por e-mail — aplique essas atualizações antes da data indicada para evitar entregas perdidas.
Mantenha a verificação de assinatura ativada, independentemente das regras de rede adicionadas.
Em plataformas serverless e de hospedagem gerenciada, a filtragem de IPs de entrada geralmente não está disponível ou é impraticável de manter. A verificação de assinatura é o controle correto nesses ambientes, e nenhuma allowlist é necessária.
Uma entrega bloqueada é tratada como qualquer outra falha e é repetida conforme o cronograma descrito em Repetições automáticas. Se as regras do firewall fizeram as entregas falhar, você poderá reenviá-las depois de corrigir as regras — consulte Repetir e recuperar mensagens.
Implemente idempotência usando o cabeçalho webhook-id para processar com segurança o mesmo evento várias vezes sem efeitos colaterais.
Secure your webhook secret
Armazene o segredo do webhook com segurança usando variáveis de ambiente ou um gerenciador de secrets. Nunca faça commit de secrets no controle de versão.
Tipo de recurso. Um dos seguintes: Payment, Subscription, Refund, Dispute, LicenseKey, CreditLedgerEntry, CreditBalanceLow, AbandonedCheckout, DunningAttempt, EntitlementGrant, ou Payout.
Os campos adicionais variam conforme o tipo de evento. Consulte a documentação específica do evento para obter os schemas completos.
Você pode testar sua integração de webhook diretamente no dashboard do Dodo Payments para garantir que seu endpoint esteja funcionando corretamente antes de entrar em produção.
1
Navigate to Webhooks
Acesse o Dashboard do Dodo Payments e vá para Developer → Webhooks.
2
Select Your Endpoint
Clique no endpoint do webhook para acessar a página de detalhes.
3
Open Testing Tab
Clique na aba Testing para acessar a interface de teste de webhook.
A aba Testing envia um payload de exemplo para este endpoint para que você possa verificar seu receiver.
1
Select Event Type
Use Select an event type para escolher o evento que deseja testar, por exemplo payment.succeeded ou payment.failed.
2
Send Example
Clique em Send example. O payload de exemplo é entregue ao URL do seu endpoint exatamente como um evento real, assinado da mesma forma.
Mensagens com falha enviadas pela aba Testing não são repetidas. Use-a para verificar seu receiver, não para testar o cronograma de repetições.
3
Check Your Endpoint
A aba registra quando o Last example sent foi enviado. Confirme que o evento chegou, que a verificação de assinatura foi aprovada e que você retornou um código de status 2xx.
Teste seu handler de webhook detalhadamente usando a interface de testes do dashboard antes de processar eventos de produção. Isso ajuda a identificar e corrigir problemas antecipadamente.
Encaminhe eventos de webhook reais da sua conta em modo de teste para o servidor de desenvolvimento local em tempo real:
dodo wh listen
A CLI abre uma conexão WebSocket com o Dodo Payments e encaminha cada evento de webhook para seu endpoint local (por exemplo, http://localhost:3000/webhook), preservando todos os cabeçalhos, incluindo os cabeçalhos de assinatura, para testes de verificação.
O listener funciona apenas com chaves de API do test mode. Execute dodo login e selecione Test Mode antes de usar este comando.
Envie payloads de webhook simulados para qualquer endpoint sem criar transações reais:
dodo wh trigger
Essa ferramenta interativa permite escolher um tipo de evento e envia um payload simulado realista para seu endpoint. Ela fica em loop para que você possa testar vários eventos em uma única sessão.O comando de acionamento abrange todos os 47 tipos de eventos que o Dodo Payments entrega, incluindo as famílias de assinatura, pagamento, reembolso, disputa, chave de licença, payout, crédito, checkout abandonado, cobrança e concessão de entitlement — consulte Supported Webhook Events para ver a lista exata.
Payloads de webhook simulados de dodo wh trigger não são assinados. Use unsafe_unwrap() em vez de unwrap() no seu handler de webhook somente durante os testes.
CLI Webhook Testing Docs
Consulte a documentação completa de testes de webhook da CLI
Adicione cabeçalhos HTTP personalizados a todas as solicitações de webhook enviadas ao seu endpoint. Isso é útil para autenticação, roteamento ou inclusão de metadados.
1
Add Headers
Na seção “Custom Headers”, insira uma Key e um Value para cada cabeçalho personalizado.
2
Add Multiple Headers
Clique no botão + para adicionar outros cabeçalhos personalizados conforme necessário.
Seus cabeçalhos personalizados são incluídos em todas as solicitações de webhook para este endpoint.
A aba Logs fornece visibilidade abrangente do status de entrega dos seus webhooks, permitindo monitorar, depurar e gerenciar eventos de webhook com eficiência.
1
Navigate to Logs Tab
Acesse Developer → Webhooks e abra a aba Logs.
2
Browse Delivery History
Veja uma tabela com todas as tentativas de entrega de webhook, com colunas para Event type, Message ID, Event ID, Sent at, Attempted at, Response code e Duration.
3
Search and Filter
Use a barra de pesquisa para encontrar mensagens específicas por ID ou tipo de evento. Filtre por status (Succeeded, Failed, Pending etc.) para se concentrar nos eventos que precisa investigar.
4
View Message Details
Clique em qualquer mensagem para abrir a página de detalhes, que mostra:
O payload completo do webhook
Cada tentativa de entrega com código de resposta e duração
O timestamp de cada tentativa
Todas as mensagens de erro do seu endpoint
Cada tentativa inclui uma ação Replay, para que você possa reenviar essa mensagem sem sair da página.
Acesse Developer → Webhooks e abra a aba Activity para visualizar o desempenho das entregas em seus endpoints.A atividade de entrega apresenta as tentativas ao longo do tempo, agrupadas como Attempts per 5 minutes, Attempts per hour ou Attempts per day, dependendo da janela. Cada barra é dividida por resultado; ao passar o cursor sobre um segmento, são exibidos o status, o número de tentativas e sua participação no total. Em um endpoint, Delivery stats (last 24h) na aba Overview resume as mesmas informações do último dia.
A coluna Error rate (24h) na aba Endpoints mostra rapidamente quais endpoints precisam de atenção, antes mesmo de você abrir qualquer um deles.
Receba uma notificação por e-mail quando as entregas de webhook para um endpoint estiverem falhando, para resolver os problemas antes que eles se transformem em um acúmulo.
1
Navigate to Settings Tab
Acesse Developer → Webhooks e abra a aba Settings.
2
Find Email Alerting
Localize o cartão Email alerting.
3
Configure Email Addresses
Insira os endereços que devem receber os alertas. Separe vários endereços com vírgulas e deixe o campo vazio para desativar os alertas.
4
Save
Clique em Save para aplicar suas alterações.
Ative os alertas por e-mail para identificar problemas de entrega de webhook antecipadamente e manter integrações confiáveis.
Pronto para implantar seu handler de webhook em produção? Fornecemos guias específicos por plataforma para ajudar você a implantar webhooks em provedores de nuvem populares, seguindo as práticas recomendadas de cada plataforma.
Vercel
Implante webhooks na Vercel com funções serverless
Cloudflare Workers
Execute webhooks na rede de edge da Cloudflare
Supabase Edge Functions
Integre webhooks com o Supabase
Netlify Functions
Implante webhooks como funções serverless da Netlify
Cada guia de plataforma inclui configuração do ambiente, verificação de assinatura e etapas de implantação específicas desse provedor.