
Key Features
Os webhooks oferecem entrega em tempo real com segurança integrada, novas tentativas automáticas e filtragem de eventos. Todos os SDKs oficiais incluem auxiliares de verificação de assinaturas, e o dashboard oferece ferramentas de teste, monitoramento e reprodução.Getting Started
Go to Developer → Webhooks
Click Add Endpoint
Enter Your Endpoint URL
Select Events
Save
Conectores de integração
Encaminhe eventos de webhook diretamente para serviços de terceiros usando conectores de integração, eliminando a necessidade de criar e manter handlers de webhook personalizados.Como os conectores funcionam
Um conector transforma eventos da Dodo Payments no formato esperado pelo destino. Os detalhes fornecidos dependem do destino:Configurando um conector
Ao criar ou editar um endpoint, selecione um conector; o painel lateral exibirá as instruções de configuração para esse destino. Teste a transformação antes de salvar para confirmar que os eventos são convertidos corretamente.Configurando eventos inscritos
Configure quais eventos cada endpoint de webhook recebe.Navigate to Webhook Endpoints
Open Event Configuration
Select Events
payment, subscription, dispute). Marque as caixas ao lado dos eventos que deseja receber. Você pode selecionar eventos individuais, um recurso inteiro ou combinar as opções.Save Configuration
Catálogo de eventos
Acesse Developer → Webhooks e abra a aba Event catalog para ver todos os tipos de evento que a Dodo Payments pode enviar. Selecione um evento para visualizar seu schema e payload de exemplo.Webhook Events Guide
Entrega de webhooks
Timeouts
Os webhooks têm um timeout de 30 segundos para operações de conexão e leitura. Processe os webhooks de forma assíncrona retornando imediatamente um código de status200 e trate o evento em segundo plano.
Novas tentativas automáticas
As entregas com falha são repetidas com backoff exponencial, em até 8 tentativas no total:Idempotência
Cada webhook inclui um headerwebhook-id exclusivo. Armazene esse ID para detectar e ignorar eventos duplicados, pois as novas tentativas podem entregar o mesmo evento várias vezes.
Ordenação de eventos
Os eventos podem chegar fora de ordem devido a novas tentativas ou condições de rede. Cada webhook inclui um campotimestamp; use-o para ordenar os eventos se sua aplicação exigir isso. Você sempre recebe o estado mais recente do payload no momento da entrega.
Protegendo webhooks
Sempre valide os payloads dos webhooks e use HTTPS.Verificando assinaturas
Cada webhook inclui um headerwebhook-signature: uma assinatura HMAC SHA256 do payload e do timestamp, assinada com sua chave secreta.
Verificação com SDK (recomendado)
Todos os SDKs oficiais incluem helpers integrados. DefinaDODO_PAYMENTS_WEBHOOK_KEY ao inicializar o client e, em seguida, chame unwrap() para verificar e analisar o payload. Há dois métodos disponíveis:
unwrap— Verifica a assinatura com sua chave secreta do webhook e, em seguida, analisa o payload.unsafe_unwrap— Analisa o payload sem verificá-lo. Use apenas para testes.
unwrap / unsafeUnwrap em TypeScript, unwrap / unsafe_unwrap em Python e Unwrap / UnsafeUnwrap em Go.
Verificação manual (alternativa)
Se você não estiver usando um SDK, verifique a assinatura por conta própria:- Crie o conteúdo assinado unindo
webhook-id,webhook-timestampe o corpo bruto da requisição com pontos:{id}.{timestamp}.{body}. Use o corpo bruto exatamente como recebido, antes de qualquer análise JSON. - Pegue seu segredo do webhook. Se ele começar com
whsec_, remova esse prefixo e, em seguida, faça a decodificação base64 do restante para obter a chave de assinatura. - Calcule o HMAC-SHA256 do conteúdo assinado usando a chave de assinatura e codifique o resultado em base64.
- O header
webhook-signaturecontém uma ou mais assinaturas separadas por espaços, cada uma no formatov1,<base64-signature>. A requisição é válida se qualquer assinaturav1corresponder à sua. Compare usando uma função de tempo constante. - Rejeite a requisição se
webhook-timestampestiver muito distante do horário atual, para evitar ataques de repetição. As bibliotecas Standard Webhooks permitem 5 minutos.
Endereços IP de origem
A verificação de assinatura é o método de autenticação compatível. Ela comprova que a requisição foi assinada com seu segredo do webhook, algo que uma verificação no nível da rede não consegue fazer. As entregas de webhooks vêm de um conjunto de endereços IP que muda com o tempo. Não dependa de allowlists de IP para autenticação. Sempre verifique o headerwebhook-signature, conforme descrito em Verificando assinaturas.
Se o firewall exigir uma allowlist:
- Não codifique endereços permanentemente. Os intervalos mudam com o tempo, e regras desatualizadas bloqueiam as entregas silenciosamente.
- Solicite os intervalos atuais pelo endereço support@dodopayments.com antes de restringir um firewall.
- Fique atento aos avisos de alteração. Quando os endereços de entrega mudarem, notificaremos os merchants afetados por e-mail — aplique as atualizações antes da data informada.
- Mantenha a verificação de assinatura ativada independentemente das regras de rede adicionadas.
Respondendo a webhooks
Seu handler de webhook deve retornar um2xx status code para confirmar o recebimento. Qualquer outra resposta é tratada como uma falha e o webhook será reenviado.
Práticas recomendadas
- Use apenas HTTPS. Endpoints HTTP estão vulneráveis à interceptação.
- Responda imediatamente. Retorne imediatamente um código de status
200e processe o evento de forma assíncrona. - Implemente idempotência. Use o header
webhook-idpara detectar e ignorar eventos duplicados. - Proteja seu segredo. Armazene
DODO_PAYMENTS_WEBHOOK_KEYem variáveis de ambiente ou em um secrets manager, nunca no controle de versão.
Estrutura do payload do webhook
Formato da requisição
Headers
Corpo da requisição
payment.succeeded, subscription.active).Exemplo de payload
Event Types
Event Payloads
Handle Payment Failures
payment.failed e recupere pagamentos recusadosTestando webhooks
Enviar um evento de exemplo
Teste sua integração de webhook diretamente no dashboard:Navigate to Webhooks
Open Testing Tab
Send Example
Check Your Endpoint
2xx.Exemplo de implementação
Implementação completa em Express.js com verificação e tratamento de webhooks:Testando webhooks com a CLI
A Dodo Payments CLI tem dois comandos para testar webhooks durante o desenvolvimento local.Escutar webhooks ativos localmente
Encaminhe eventos de webhook reais da sua conta em modo de teste para o servidor de desenvolvimento local:http://localhost:3000/webhook), preservando todos os headers para os testes de verificação de assinatura.
dodo login e selecione Test Mode primeiro.Acionar eventos de webhook simulados
Envie payloads de webhook simulados para qualquer endpoint sem criar transações reais:subscription.past_due nem subscription.unpaused. Consulte Supported Webhook Events para ver a lista exata.
CLI Webhook Testing Docs
Configurações avançadas
A aba Advanced 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. Por padrão, os webhooks não têm limite de taxa aplicado e os eventos são entregues assim que ocorrem.Open Advanced Tab
Configure Rate Limit
Set Your Limit
Headers personalizados
Adicione headers HTTP personalizados a todas as requisições de webhook enviadas ao seu endpoint. Útil para autenticação, roteamento ou adição de metadados.Add Headers
Add Multiple Headers
Transformações
As transformações permitem modificar o payload de um webhook e, opcionalmente, redirecioná-lo para uma URL diferente. Use transformações para:- Modificar a estrutura do payload antes do processamento
- Encaminhar webhooks para endpoints diferentes com base no conteúdo
- Adicionar ou remover campos do payload
- Transformar formatos de dados
Enable Transformations
Configure Transformation
handler().Test Transformation
Monitorando logs de webhook
A aba Logs oferece visibilidade sobre o status de entrega dos seus webhooks.Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- 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
Monitoramento de atividade
Acesse Developer → Webhooks e abra a aba Activity para ver o desempenho das entregas em seus endpoints. Delivery activity mostra as tentativas ao longo do tempo, agrupadas como Attempts per 5 minutes, Attempts per hour ou Attempts per day, dependendo do intervalo. Cada barra é dividida por resultado; ao passar o mouse 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.Reproduzindo e recuperando mensagens
A forma de reenviar uma mensagem depende de quantas você precisa reenviar:- Uma mensagem — abra-a na aba Logs e use a ação Replay na tentativa.
- Um intervalo de mensagens — abra o endpoint, pois os modos em massa atuam em um único endpoint por vez.
Reproduzindo em massa
Abra o endpoint em Developer → Webhooks. Há três modos disponíveis, cada um atuando somente nesse endpoint:Open More Actions
Set the Range
Start the Run