Guia de Eventos de Webhook

O Dodo Payments fornece notificações de webhook em tempo real para mantê-lo informado sobre eventos críticos relacionados a transações, assinaturas, reembolsos, disputas e gerenciamento de chaves de licença. Abaixo está um guia detalhado para esses eventos, categorizados para clareza, juntamente com dicas e considerações de implementação.

Eventos de Pagamento

Nome do Evento	Tipo de Evento	Descrição
Payment Succeeded	`payment.succeeded`	Acionado quando um pagamento é processado com sucesso.
Payment Failed	`payment.failed`	Ocorre quando uma tentativa de pagamento falha devido a erros, cartões recusados ou outros problemas.
Payment Processing	`payment.processing`	Indica que um pagamento está sendo processado no momento.
Payment Cancelled	`payment.cancelled`	Acionado quando um pagamento é cancelado antes da conclusão.

Eventos de Reembolso

Nome do Evento	Tipo de Evento	Descrição
Refund Succeeded	`refund.succeeded`	Acionado quando um reembolso é processado com sucesso.
Refund Failed	`refund.failed`	Ocorre quando uma tentativa de reembolso falha devido a erros de processamento ou outros problemas.

Eventos de Disputa

Nome do Evento	Tipo de Evento	Descrição
Dispute Opened	`dispute.opened`	Acionado quando um cliente inicia uma disputa.
Dispute Expired	`dispute.expired`	Indica que uma disputa expirou sem resolução.
Dispute Accepted	`dispute.accepted`	Acionado quando um comerciante aceita a disputa.
Dispute Cancelled	`dispute.cancelled`	Ocorre quando uma disputa é cancelada pelo cliente ou pelo sistema.
Dispute Challenged	`dispute.challenged`	Acionado quando um comerciante contesta uma disputa.
Dispute Won	`dispute.won`	Indica que o comerciante venceu com sucesso uma disputa.
Dispute Lost	`dispute.lost`	Ocorre quando o comerciante perde uma disputa.

Eventos de Assinatura

Nome do evento	Tipo de evento	Descrição
Assinatura ativa	`subscription.active`	Indica que uma assinatura está ativa e que cobranças recorrentes estão agendadas.
Assinatura atualizada	`subscription.updated`	Acionado quando qualquer campo da assinatura é atualizado (sincronização em tempo real sem polling).
Assinatura em espera	`subscription.on_hold`	Acionado quando uma assinatura é temporariamente colocada em espera devido a uma renovação malsucedida.
Assinatura pausada	`subscription.paused`	Acionado quando uma assinatura é pausada.
Assinatura retomada	`subscription.unpaused`	Acionado quando uma assinatura pausada é retomada.
Assinatura renovada	`subscription.renewed`	Ocorre quando uma assinatura é renovada com sucesso.
Plano da assinatura alterado	`subscription.plan_changed`	Acionado quando uma assinatura é atualizada, reduzida ou modificada com addons diferentes.
Método de pagamento da assinatura atualizado	`subscription.update_payment_method`	Enviado quando o método de pagamento de uma assinatura é atualizado. Contém o payload da assinatura.
Assinatura cancelada	`subscription.cancelled`	Acionado quando uma assinatura é cancelada pelo comerciante ou pelo cliente.
Assinatura malsucedida	`subscription.failed`	Indica uma assinatura malsucedida. Isso significa que não foi possível criar um mandato.
Assinatura expirada	`subscription.expired`	Acionado quando uma assinatura chega ao fim de seu período e expira.

Eventos de Chave de Licença

Nome do Evento	Tipo de Evento	Descrição
License Key Created	`license_key.created`	Acionado quando uma nova chave de licença é criada para um produto.

Eventos de Concessão de Direitos

Nome do Evento	Tipo de Evento	Descrição
Grant Created	`entitlement_grant.created`	Uma nova concessão de direitos é criada para um cliente. Concessões de chave de licença chegam `delivered`; concessões baseadas em OAuth (Discord, GitHub, Notion) chegam `pending`.
Grant Delivered	`entitlement_grant.delivered`	O cumprimento da concessão é concluído — chave de licença emitida, links de arquivo resolvidos ou acesso à plataforma concedido.
Grant Failed	`entitlement_grant.failed`	O cumprimento da concessão falhou; inspeccionar `error_code` e `error_message`.
Grant Revoked	`entitlement_grant.revoked`	Acesso retirado; inspecionar `revocation_reason` (estado da assinatura, reembolso, mudança de plano ou manual).

Para esquemas de payload detalhados, eventos de exemplo e referência completa revocation_reason, veja Webhooks de Concessão de Direitos.

Eventos de Crédito

Nome do Evento	Tipo de Evento	Descrição
Crédito Adicionado	`credit.added`	Acionado quando créditos são concedidos a um cliente (assinatura, única vez, complementar ou API).
Crédito Deduzido	`credit.deducted`	Ocorre quando créditos são consumidos por uso ou débito manual.
Crédito Expirado	`credit.expired`	Acionado quando créditos não utilizados expiram após o período de expiração configurado.
Crédito Transferido	`credit.rolled_over`	Ocorre quando créditos não utilizados são transferidos para uma nova concessão no final do ciclo.
Rollover Perdido	`credit.rollover_forfeited`	Acionado quando créditos são perdidos porque o número máximo de transferências foi atingido.
Cobrança por Excesso	`credit.overage_charged`	Ocorre quando cobranças por excesso são aplicadas por uso além do saldo zero.
Excesso Reiniciado	`credit.overage_reset`	Acionado quando cobranças acumuladas por excesso são reiniciadas (por exemplo, no início de um novo ciclo de cobrança).
Ajuste Manual	`credit.manual_adjustment`	Acionado quando é feito um ajuste manual de crédito ou débito.
Saldo Baixo	`credit.balance_low`	Acionado quando o saldo de crédito cai abaixo do limite configurado.

Eventos de Recuperação

Nome do Evento	Tipo de Evento	Descrição
Abandoned Checkout Detected	`abandoned_checkout.detected`	Acionado quando um checkout incompleto ou falhado é detectado após 60 minutos.
Abandoned Checkout Recovered	`abandoned_checkout.recovered`	Ocorre quando um cliente completa o pagamento através de um link de recuperação.

Para esquemas de payload detalhados, descrições de campos e exemplos de manipuladores, consulte Webhooks de Recuperação.

Eventos de Cobrança

Nome do Evento	Tipo de Evento	Descrição
Dunning Started	`dunning.started`	Acionado quando uma tentativa de cobrança começa para uma assinatura que foi suspensa ou cancelada.
Dunning Recovered	`dunning.recovered`	Ocorre quando um cliente atualiza seu método de pagamento e a cobrança resultante tem sucesso.

Para esquemas de payload detalhados, descrições de campos e exemplos de manipuladores, veja Webhooks de Recuperação.

Eventos de Payout

Esses eventos acompanham a movimentação dos seus fundos do Dodo Payments para sua conta bancária, refletindo os status de payout exibidos no dashboard. O payload é um objeto de payout com a mesma estrutura de uma entrada de GET /payouts.

Nome do evento	Tipo de evento	Descrição
Payout criado	`payout.created`	Acionado quando um payout é criado, seja pelo ciclo automático de payout ou fora do ciclo.
Payout em andamento	`payout.in_progress`	Ocorre quando a data de vencimento do payout chega e o payout começa a ser processado.
Payout em espera	`payout.on_hold`	Acionado quando um payout é pausado ou colocado em análise.
Payout bem-sucedido	`payout.success`	Ocorre quando o payout para sua conta bancária é processado com sucesso.
Falha no payout	`payout.failed`	Acionado quando um payout falha. Os fundos e as taxas são creditados novamente na sua carteira.

Não presuma que os eventos de payout sejam finais ou estejam estritamente ordenados. payout.failed pode chegar legitimamente após payout.success quando um banco devolve a transferência, e payout.success pode chegar após payout.failed quando um payout com falha é recuperado posteriormente. Sempre considere o status no payload como o estado atual.

payout.created era emitido anteriormente como payout.not_initiated. Se você tiver um endpoint existente filtrando por payout.not_initiated, atualize o filtro para payout.created para que ele continue correspondendo.

Para obter esquemas detalhados de payloads, descrições de campos e exemplos de handlers, consulte Payout Webhooks. Esses eventos de webhook foram desenvolvidos para fornecer aos merchants atualizações essenciais para gerenciar suas operações com eficiência. Implemente handlers robustos para cada evento relevante na sua integração de webhook para garantir uma funcionalidade estável e confiável.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Eventos de Pagamento

Eventos de Reembolso

Eventos de Disputa

Eventos de Assinatura

Eventos de Chave de Licença

Eventos de Concessão de Direitos

Eventos de Crédito

Eventos de Recuperação

Eventos de Cobrança

Eventos de Payout

​Eventos de Pagamento

​Eventos de Reembolso

​Eventos de Disputa

​Eventos de Assinatura

​Eventos de Chave de Licença

​Eventos de Concessão de Direitos

​Eventos de Crédito

​Eventos de Recuperação

​Eventos de Cobrança

​Eventos de Payout

Eventos de Pagamento

Eventos de Reembolso

Eventos de Disputa

Eventos de Assinatura

Eventos de Chave de Licença

Eventos de Concessão de Direitos

Eventos de Crédito

Eventos de Recuperação

Eventos de Cobrança

Eventos de Payout