Skip to main content
Imagem de Capa do Webhook
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.

Key Features

Real-time Delivery

Receive instant notifications when events occur

Secure by Default

HMAC SHA256 signature verification included

Automatic Retries

Built-in retry logic with exponential backoff

Event Filtering

Subscribe only to events you need

Getting Started

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.

Integration Connectors

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.

Como os conectores funcionam

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: 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.

Configurando um conector

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.

Configurando eventos inscritos

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.

Event Catalog

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.

Entrega de webhook

Timeouts

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.

Retries automáticos

Se uma entrega de webhook falhar, o Dodo Payments fará novas tentativas automaticamente com exponential backoff para evitar sobrecarregar seu sistema.
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.

Idempotência

Cada evento de webhook inclui um header webhook-id exclusivo. Use esse identificador para implementar idempotência e evitar processamento duplicado.
Sempre implemente verificações de idempotência. Devido aos retries, você poderá receber o mesmo evento várias vezes.

Ordem dos eventos

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.

Protegendo webhooks

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

Verificando assinaturas

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.

Verificação com SDK (recomendada)

Todos os SDKs oficiais incluem helpers integrados para validar e analisar com segurança os webhooks recebidos. Há dois métodos disponíveis:
  • unwrap(): verifica assinaturas usando sua webhook secret key
  • unsafe_unwrap(): analisa payloads sem verificação
Forneça seu webhook secret por meio de DODO_PAYMENTS_WEBHOOK_KEY ao inicializar o cliente do Dodo Payments.

Verificação manual (alternativa)

Se você não estiver usando um SDK, poderá verificar as assinaturas seguindo a especificação Standard Webhooks:
  1. Crie a mensagem assinada concatenando webhook-id, webhook-timestamp e a string bruta exata serializada de payload, separados por pontos (.).
  2. Calcule o HMAC SHA256 dessa string usando sua webhook secret key do Dashboard.
  3. Compare a assinatura calculada com o header webhook-signature. Se forem iguais, o webhook é autêntico.
Seguimos a especificação Standard Webhooks. Você pode usar as bibliotecas correspondentes para verificar assinaturas: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Para formatos de payload de eventos, consulte Webhook Payload.

Endereços IP de origem

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.

Responder a Webhooks

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

Práticas recomendadas

Sempre use URLs HTTPS para endpoints de webhook. Endpoints HTTP são vulneráveis a ataques man-in-the-middle e expõem os dados do seu webhook.
Retorne imediatamente um código de status 200 ao receber o webhook. Processe o evento de forma assíncrona para evitar timeouts.
Implemente idempotência usando o cabeçalho webhook-id para processar com segurança o mesmo evento várias vezes sem efeitos colaterais.
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.

Estrutura do Payload do Webhook

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

Formato da solicitação

Cabeçalhos

string
obrigatório
Identificador exclusivo deste evento de webhook. Use-o nas verificações de idempotência.
string
obrigatório
Assinatura HMAC SHA256 para verificar a autenticidade do webhook.
string
obrigatório
Timestamp Unix, em segundos, de quando o webhook foi enviado.

Corpo da solicitação

string
obrigatório
Identificador da sua empresa no Dodo Payments.
string
obrigatório
Tipo de evento que acionou este webhook (por exemplo, payment.succeeded, subscription.active).
string
obrigatório
Timestamp formatado em ISO 8601 de quando o evento ocorreu.
object
obrigatório
Payload específico do evento contendo informações detalhadas sobre ele.

Exemplo de Payload

Event Types

Consulte todos os tipos de eventos de webhook disponíveis

Event Payloads

Consulte os schemas detalhados de payload para cada evento

Handle Payment Failures

Reaja a payment.failed e recupere pagamentos recusados

Testar Webhooks

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.

Enviar um evento de exemplo

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.

Exemplo de implementação

Este é um exemplo completo de implementação com Express.js que mostra a verificação e o tratamento de webhooks:
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.

Testar Webhooks com a CLI

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

Escutar Webhooks em tempo real localmente

Encaminhe eventos de webhook reais da sua conta em modo de teste para o servidor de desenvolvimento local em tempo real:
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.

Acionar eventos de webhook simulados

Envie payloads de webhook simulados para qualquer endpoint sem criar transações reais:
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

Configurações avançadas

A aba Advanced fornece opções de configuração adicionais para ajustar o comportamento do endpoint do webhook.

Limitação de taxa (throttling)

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

Open Advanced Tab

Na página de detalhes do endpoint, clique na aba Advanced.
2

Configure Rate Limit

Na seção “Rate Limit (throttling)”, clique em Edit para modificar as configurações de limitação de taxa.
Por padrão, nenhum limite de taxa é aplicado aos webhooks, o que significa que os eventos são entregues assim que ocorrem.
3

Set Your Limit

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

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

Transformações

As transformações permitem modificar o payload de um webhook e, opcionalmente, redirecioná-lo para um URL diferente. Esse recurso avançado permite:
  • 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
1

Enable Transformations

Ative o botão Enabled para ativar o recurso de transformação.
2

Configure Transformation

Clique em Edit transformation para definir suas regras de transformação usando JavaScript.
3

Test Transformation

Use a interface de testes de transformação para verificar se ela funciona corretamente antes de entrar em produção.
As transformações podem afetar o desempenho da entrega de webhooks. Teste detalhadamente 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 calculados ao payload
  • Encaminhar eventos para diferentes microsserviços

Monitorar logs de webhook

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.

Monitoramento de atividades

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.

Repetir e recuperar mensagens

A forma de reenviar uma mensagem depende da quantidade necessária:
  • Uma mensagem — abra-a na aba Logs e use a ação Replay na tentativa. Não é necessário abrir o endpoint.
  • Um intervalo de mensagens — abra o endpoint, pois os modos em massa atuam em um único endpoint por vez.

Repetir em massa

Abra o endpoint em Developer → Webhooks. Há três modos disponíveis, cada um atuando somente nesse endpoint. O intervalo definido depende do modo:
1

Open More Actions

No endpoint, abra More actions e escolha um dos três modos acima.
2

Set the Range

Preencha o intervalo solicitado pelo modo, conforme listado na tabela.
3

Start the Run

Clique em Recover ou Replay, dependendo do modo escolhido.
Cada execução aparece em Replay history, na aba Overview do endpoint, com seu modo, intervalo de tempo, status e número de mensagens reenviadas.

Alertas por e-mail

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.

Implantar em plataformas de nuvem

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.

Referência da API relacionada

Create Webhook

Referência da API para criar e configurar endpoints de webhook programaticamente

List Webhooks

Referência da API para recuperar e gerenciar seus endpoints de webhook
Última modificação em 21 de agosto de 2026