Skip to main content
Imagem de Capa do Webhook
Os webhooks enviam notificações em tempo real quando eventos ocorrem na sua conta da Dodo Payments. Use-os para automatizar fluxos de trabalho, atualizar seu banco de dados, enviar notificações e manter seus sistemas sincronizados.
Os webhooks da Dodo Payments seguem a especificação Standard Webhooks para verificação de assinaturas e estrutura de payloads.

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

1

Go to Developer → Webhooks

No Dodo Payments Dashboard, navegue até Developer → Webhooks.
2

Click Add Endpoint

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

Enter Your Endpoint URL

Forneça a URL HTTPS para a qual a Dodo Payments enviará eventos de webhook ou selecione um conector de integração (Slack, Discord, Zapier, Resend etc.) para encaminhar eventos a um serviço de terceiros sem escrever código.
4

Select Events

Escolha quais eventos receber. Os eventos são organizados por recurso (pagamento, assinatura, disputa etc.). Você pode selecionar eventos individuais ou um recurso inteiro para receber todos os eventos relacionados.
5

Save

Clique em Create endpoint. Seu segredo de assinatura do webhook aparece na aba Overview do endpoint.
Mantenha seu segredo de webhook seguro. Nunca o exponha em código do lado do cliente ou no controle de versão.
Para alternar seu segredo de webhook, abra o endpoint e clique em Rotate secret ao lado do segredo na aba Overview. O segredo antigo permanece válido por 24 horas após a rotação.

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: O dashboard mostra todos os conectores disponíveis para sua empresa. Consulte External Integrations para saber o que cada destino pode fazer com os eventos.

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

Configure quais eventos cada endpoint de webhook recebe.
1

Navigate to Webhook Endpoints

Acesse Developer → Webhooks e clique no seu endpoint.
2

Open Event Configuration

Clique em Edit para abrir o painel lateral de configuração do endpoint.
3

Select Events

O seletor de tipo de evento exibe todos os eventos de webhook disponíveis em uma árvore pesquisável, agrupados por recurso (por exemplo, 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.
4

Save Configuration

Clique em Save para aplicar suas alterações.
Se você desmarcar todos os eventos, seu endpoint de webhook receberá todos os tipos de evento. Selecione apenas os eventos necessários para sua aplicação.

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

Consulte os eventos como documentação de referência, agrupados por recurso.

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 status 200 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: Use o dashboard para reproduzir manualmente mensagens com falha ou recuperar em massa mensagens de um intervalo de tempo específico.

Idempotência

Cada webhook inclui um header webhook-id exclusivo. Armazene esse ID para detectar e ignorar eventos duplicados, pois as novas tentativas podem entregar o mesmo evento várias vezes.
Sempre implemente verificações de idempotência. Devido às novas tentativas, você pode receber 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 campo timestamp; 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 header webhook-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. Defina DODO_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.
Os nomes dos métodos seguem as convenções de cada linguagem: unwrap / unsafeUnwrap em TypeScript, unwrap / unsafe_unwrap em Python e Unwrap / UnsafeUnwrap em Go.
Forneça seu segredo do webhook por meio de DODO_PAYMENTS_WEBHOOK_KEY ao inicializar o client do Dodo Payments.

Verificação manual (alternativa)

Se você não estiver usando um SDK, verifique a assinatura por conta própria:
  1. Crie o conteúdo assinado unindo webhook-id, webhook-timestamp e o corpo bruto da requisição com pontos: {id}.{timestamp}.{body}. Use o corpo bruto exatamente como recebido, antes de qualquer análise JSON.
  2. 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.
  3. Calcule o HMAC-SHA256 do conteúdo assinado usando a chave de assinatura e codifique o resultado em base64.
  4. O header webhook-signature contém uma ou mais assinaturas separadas por espaços, cada uma no formato v1,<base64-signature>. A requisição é válida se qualquer assinatura v1 corresponder à sua. Compare usando uma função de tempo constante.
  5. Rejeite a requisição se webhook-timestamp estiver muito distante do horário atual, para evitar ataques de repetição. As bibliotecas Standard Webhooks permitem 5 minutos.
Consulte as bibliotecas Standard Webhooks para ver implementações de referência. Para formatos de payload de eventos, consulte o Webhook Payload.

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 header webhook-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.
Em plataformas serverless e de hospedagem gerenciada, a filtragem de IP de entrada geralmente não está disponível ou não é prática. A verificação de assinatura é o controle correto nesses ambientes.
Uma entrega bloqueada é tratada como uma falha e repetida de acordo com o cronograma descrito em Novas tentativas automáticas. Se as regras do firewall causaram falhas nas entregas, você poderá reenviá-las depois de corrigir as regras — consulte Reproduzindo e recuperando mensagens.

Respondendo a webhooks

Seu handler de webhook deve retornar um 2xx 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 200 e processe o evento de forma assíncrona.
  • Implemente idempotência. Use o header webhook-id para detectar e ignorar eventos duplicados.
  • Proteja seu segredo. Armazene DODO_PAYMENTS_WEBHOOK_KEY em 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

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 requisição

string
obrigatório
Identificador da empresa do 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 o evento.

Exemplo de payload

Event Types

Consulte todos os tipos de eventos de webhook disponíveis

Event Payloads

Consulte schemas detalhados de payload para cada evento

Handle Payment Failures

Reaja a payment.failed e recupere pagamentos recusados

Testando webhooks

Enviar um evento de exemplo

Teste sua integração de webhook diretamente no dashboard:
1

Navigate to Webhooks

Acesse Developer → Webhooks e clique no seu endpoint.
2

Open Testing Tab

Clique na aba Testing.
3

Send Example

Selecione um tipo de evento e clique em Send example. O payload de exemplo será entregue à URL do seu endpoint exatamente como um evento real, com a mesma assinatura.
4

Check Your Endpoint

Confirme que o evento chegou, que a verificação da assinatura foi aprovada e que você retornou um código de status 2xx.
As mensagens com falha enviadas pela aba Testing são repetidas de acordo com o cronograma normal, como qualquer outro webhook.

Exemplo de implementação

Implementação completa em Express.js com verificação e 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.

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:
A CLI abre uma conexão WebSocket e encaminha cada evento de webhook para seu endpoint local (por exemplo, http://localhost:3000/webhook), preservando todos os headers para os testes de verificação de assinatura.
O listener funciona apenas com API keys do modo de teste. Execute 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:
Essa ferramenta interativa permite escolher um tipo de evento e envia um payload simulado realista para seu endpoint. Ela entra em loop para que você possa testar vários eventos em uma única sessão. O comando de acionamento abrange as famílias de assinatura, pagamento, reembolso, contestação, license key, repasse, crédito, checkout abandonado, cobrança e concessão de entitlement. Ele não envia subscription.past_due nem subscription.unpaused. Consulte Supported Webhook Events para ver a lista exata.
Os payloads de webhook simulados de dodo wh trigger não são assinados. Use o método de análise sem verificação (unsafeUnwrap em TypeScript, unsafe_unwrap em Python e UnsafeUnwrap em Go) 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 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.
1

Open Advanced Tab

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

Configure Rate Limit

Expanda a seção Endpoint throttling.
3

Set Your Limit

Informe o número máximo de mensagens por segundo e clique em Save. As entregas acima dessa taxa são enfileiradas, não descartadas.

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

Add Headers

Na seção Custom headers, informe um nome e um valor para o header.
2

Add Multiple Headers

Clique em Add header para cada header adicional e depois clique em Save.

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
1

Enable Transformations

Na seção Transformation, ative Enable transformation.
2

Configure Transformation

Escreva suas regras de transformação em JavaScript no editor de código e clique em Save. O código deve retornar o objeto de webhook de handler().
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.

Monitorando logs de webhook

A aba Logs oferece visibilidade sobre o status de entrega dos seus webhooks.
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 e 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 precisam ser investigados.
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 reenviar somente essa mensagem sem sair da página.

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.
A coluna Error rate (24h) na aba Endpoints mostra rapidamente quais endpoints precisam de atenção.

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

O dashboard de webhooks não oferece alertas por e-mail para entregas com falha. Para monitorar as entregas, acesse Developer → Webhooks e verifique as abas Logs e Activity.

Deploy em plataformas de nuvem

Guias específicos de plataformas para fazer deploy de handlers de webhook em provedores de nuvem populares:

Vercel

Faça deploy de webhooks na Vercel com funções serverless

Cloudflare Workers

Execute webhooks na rede edge da Cloudflare

Supabase Edge Functions

Integre webhooks com o Supabase

Netlify Functions

Faça deploy de webhooks como funções serverless da Netlify

Referência relacionada da API

Create Webhook

Crie e configure endpoints de webhook programaticamente

List Webhooks

Recupere e gerencie seus endpoints de webhook
Última modificação em 26 de setembro de 2026