
Nossa implementação de webhooks segue as especificações do Standard Webhooks, garantindo compatibilidade com as melhores práticas do setor e bibliotecas de webhook existentes.
Principais Recursos
Real-time Delivery
Receba notificações instantâneas quando eventos acontecerem
Secure by Default
Verificação de assinatura HMAC SHA256 inclusa
Automatic Retries
Lógica de tentativa automática com backoff exponencial integrada
Event Filtering
Inscreva-se somente nos eventos que você precisa
Começando
Select Events to Receive
Escolha os eventos específicos que seu endpoint de webhook deve escutar selecionando-os na lista de eventos.
Get Secret Key
Obtenha seu
Secret Key de webhook na página de configurações. Você usará isso para verificar a autenticidade dos webhooks recebidos.Configurando Eventos Inscritos
Você pode configurar quais eventos específicos deseja receber para cada endpoint de webhook.Acessando a Configuração de Eventos
Gerenciando Inscrições de Eventos
View Available Events
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).Search and Filter
Use a barra de pesquisa para encontrar rapidamente eventos específicos digitando nomes ou palavras-chave.
Select Events
Marque as caixas ao lado dos eventos que deseja receber. Você pode:
- Selecionar subeventos individuais (por exemplo,
dispute.accepted,dispute.challenged) - Selecionar eventos principais para receber todos os subeventos relacionados
- Misturar e combinar eventos específicos com base nas suas necessidades
Review Event Details
Passe o cursor sobre o ícone de informação (ⓘ) ao lado de cada evento para ver uma descrição de quando aquele evento é disparado.
Entrega de Webhook
Timeouts
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.Tentativas Automáticas
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 reenvio 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.
Idempotência
Cada evento de webhook inclui um cabeçalho únicowebhook-id. Use esse identificador para implementar idempotência e evitar processamento duplicado.
Ordenação de Eventos
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 payload mais recente no momento da entrega, independentemente de quando o evento de webhook foi originalmente emitido.
Protegendo Webhooks
Para garantir a segurança de seus webhooks, sempre valide os payloads e use HTTPS.Verificando Assinaturas
Cada solicitação de webhook inclui um cabeçalhowebhook-signature, uma assinatura HMAC SHA256 do payload e do timestamp do webhook, assinada com sua chave secreta.
Verificação de SDK (recomendada)
Todos os SDKs oficiais incluem helpers embutidos para validar e analisar com segurança os webhooks recebidos. Duas métodos estão disponíveis:unwrap(): Verifica assinaturas usando sua chave secreta de webhookunsafe_unwrap(): Analisa payloads sem verificação
Verificação Manual (alternativa)
Se você não estiver usando um SDK, pode verificar assinaturas você mesmo seguindo a especificação Standard Webhooks:- Construa a mensagem assinada concatenando
webhook-id,webhook-timestampe a string JSON bruta exatapayload, separadas por pontos (.). - Calcule o HMAC SHA256 dessa string usando sua chave secreta de webhook do Painel.
- Compare a assinatura calculada com o cabeçalho
webhook-signature. Se eles coincidirem, o webhook é autêntico.
Seguimos a especificação do Standard Webhooks. Você pode usar as bibliotecas deles para verificar assinaturas: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Para formatos de payload de evento, veja o Webhook Payload.
Respondendo a Webhooks
- Seu manipulador de webhook deve retornar um
2xx status codepara reconhecer o recebimento do evento. - Qualquer outra resposta será tratada como uma falha, e o webhook será reenviado.
Melhores Práticas
Use HTTPS endpoints only
Use HTTPS endpoints only
Sempre use URLs HTTPS para endpoints de webhook. Endpoints HTTP são vulneráveis a ataques man-in-the-middle e expõem seus dados de webhook.
Respond immediately
Respond immediately
Retorne um código de status
200 imediatamente ao receber o webhook. Processe o evento assincronamente para evitar timeouts.Handle duplicate events
Handle duplicate events
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
Secure your webhook secret
Armazene seu segredo de webhook com segurança usando variáveis de ambiente ou um gerenciador de segredos. Nunca envie segredos para o controle de versão.
Estrutura do Payload do Webhook
Entender a estrutura do payload do webhook ajuda você a analisar e processar eventos corretamente.Formato da Solicitação
Cabeçalhos
Identificador único para este evento de webhook. Use-o para checagens de idempotência.
Assinatura HMAC SHA256 para verificar a autenticidade do webhook.
Timestamp Unix (em segundos) quando o webhook foi enviado.
Corpo da Solicitação
Seu identificador comercial Dodo Payments.
Tipo de evento que acionou este webhook (por exemplo,
payment.succeeded, subscription.active).Timestamp formatado em ISO 8601 de quando o evento ocorreu.
Payload específico do evento contendo informações detalhadas sobre o evento.
Exemplo de Payload
Event Types
Navegue por todos os tipos de eventos de webhook disponíveis
Event Payloads
Visualize esquemas de payload detalhados para cada evento
Testando Webhooks
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.
Acessando a Interface de Teste
Testando Seu Webhook
A interface de teste fornece uma maneira abrangente de testar seu endpoint de webhook:Select Event Type
Use o menu suspenso para selecionar o tipo de evento específico que deseja testar (por exemplo,
payment.succeeded, payment.failed, etc.).O menu contém todos os tipos de eventos de webhook disponíveis que seu endpoint pode receber.
Review Schema and Example
A interface exibe tanto o Esquema (estrutura de dados) quanto o Exemplo (payload de amostra) para o tipo de evento selecionado.
Verificando Seu Teste
Check Your Endpoint
Monitore os logs do seu endpoint de webhook para confirmar que o evento de teste foi recebido.
Verify Signature
Verifique se a validação de assinatura está funcionando corretamente com o payload de teste.
Exemplo de Implementação
Aqui está uma implementação completa do Express.js mostrando verificação e manipulação de webhook:Testando Webhooks com a CLI
O CLI Dodo Payments fornece dois comandos para testar webhooks durante o desenvolvimento local, sem precisar sair do terminal.Ouvir Webhooks Ao Vivo Localmente
Encaminhe eventos reais de webhook da sua conta em modo de teste para seu servidor local em tempo real:http://localhost:3000/webhook), preservando todos os cabeçalhos, incluindo cabeçalhos de assinatura para testes de verificação.
O ouvinte funciona apenas com chaves de API em modo de teste. Execute
dodo login e selecione o Modo de Teste antes de usar este comando.Acionar Eventos de Webhook Mock
Envie payloads simulados de webhook para qualquer endpoint sem criar transações reais:CLI Webhook Testing Docs
Consulte a documentação completa da CLI para testes de webhook
Configurações Avançadas
A aba Configurações Avançadas 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 para evitar sobrecarregar seu sistema.Configure Rate Limit
Clique no botão Editar para modificar as configurações de limite de taxa.
Por padrão, os webhooks não têm “Limite de taxa” aplicado, ou seja, os eventos são entregues assim que ocorrem.
Cabeçalhos Personalizados
Adicione cabeçalhos HTTP personalizados a todas as requisições de webhook enviadas para seu endpoint. Isso é útil para autenticação, roteamento ou adicionar metadados às suas requisições.Add Custom Header
Na seção “Cabeçalhos Personalizados”, insira uma Chave e um Valor para seu cabeçalho.
Add Multiple Headers
Clique no botão + para adicionar cabeçalhos personalizados adicionais conforme necessário.
Transformações
As transformações permitem que você modifique o payload de um webhook e redirecione para uma URL diferente. Esse recurso poderoso possibilita que você:- Modifique a estrutura do payload antes do processamento
- Direcione webhooks para endpoints diferentes com base no conteúdo
- Adicione ou remova campos do payload
- Transforme formatos de dados
Configure Transformation
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.
Monitoramento de Logs de Webhook
A aba Logs fornece visibilidade abrangente sobre o status de entrega dos seus webhooks, permitindo monitorar, depurar e gerenciar eventos de webhook de forma eficaz.
Monitoramento de Atividades
A aba Atividades fornece insights em tempo real sobre o desempenho da entrega dos seus webhooks com análises visuais.
Alertas por E-mail
Mantenha-se informado sobre a saúde dos seus webhooks com notificações automáticas por e-mail. Quando as entregas de webhooks começarem a falhar ou seu endpoint parar de responder, você receberá alertas por e-mail para que possa agir rapidamente e manter suas integrações funcionando sem problemas.
Ativar Alertas por E-mail
Navigate to Alerting Settings
Vá para o Painel Dodo Payments e navegue até Dashboard → Webhooks → Alertas.
Enable Email Notifications
Ative Notificações por e-mail para começar a receber alertas sobre problemas de entrega de webhooks.
Implantar em Plataformas em Nuvem
Pronto para implantar seu manipulador de webhook em produção? Fornecemos guias específicos para cada plataforma que ajudam você a implantar webhooks em provedores de nuvem populares com as melhores práticas para cada ambiente.Vercel
Implemente webhooks no Vercel com funções serverless
Cloudflare Workers
Execute webhooks na rede edge da Cloudflare
Supabase Edge Functions
Integre webhooks com o Supabase
Netlify Functions
Implemente webhooks como funções serverless do Netlify
Cada guia de plataforma inclui configuração de ambiente, verificação de assinatura e etapas de implantação específicas para o provedor.
