Skip to main content

​
Visão Geral

A Autorizou envia webhooks para eventos do ciclo de vida de pagamentos e assinaturas. Você escolhe quais eventos deseja receber ao configurar seu webhook na Dashboard. Esta página lista apenas os eventos que a plataforma realmente emite. O valor técnico enviado no campo event do payload é sempre o formato em inglês (ex.: payment.authorized).
Autenticidade da origem: configure um secret no seu webhook e valide a assinatura de cada entrega (veja Validando a assinatura). Sem secret configurado, a entrega sai sem assinatura e você não tem como provar a origem.Mesmo com assinatura válida, trate a notificação como um gatilho: a ordem de entrega não é garantida e duplicatas são possíveis. Use o header X-Autorizou-Delivery para idempotência e confirme o estado com GET /payments/{identifier} antes de agir sobre dinheiro.
Configure apenas os eventos que você realmente precisa processar, para reduzir o volume de notificações.

​
Eventos de Pagamento

​
Criação, autorização e captura

Disparado quando um pagamento é criado no sistema.Quando usar: registrar o início de um pagamento, criar um registro pendente no seu sistema, analytics de conversão.Aplicável a: todos os métodos de pagamento.
Disparado quando um pagamento com captura manual é pré-autorizado — o valor foi reservado no cartão, mas ainda não capturado.Quando usar: confirmar que há saldo/limite reservado, iniciar a validação do pedido antes de capturar.Aplicável a: cartão de crédito (captura manual).
Disparado quando um pagamento é autorizado.Quando usar: confirmar a aprovação, liberar produto/serviço (em captura automática), enviar confirmação ao cliente, iniciar fulfillment.Aplicável a: cartão de crédito, PIX Recorrente (mandato criado).
Em captura manual, este evento indica apenas autorização — o valor ainda não foi capturado (aguarde payment.capture_confirmed).
Disparado quando a captura é confirmada — o valor pré-autorizado foi efetivamente capturado.Quando usar: liberar o pedido após captura, marcar a venda como concluída, registros contábeis.Aplicável a: cartão de crédito (captura manual e cobranças recorrentes).
Disparado quando a captura de um valor pré-autorizado falha.Quando usar: alertar a equipe, tentar nova captura dentro do prazo, ou cancelar o pedido.Aplicável a: cartão de crédito (captura manual).

​
Recusa, expiração e fraude

Disparado quando um pagamento é recusado.Quando usar: notificar o cliente, oferecer método alternativo, liberar estoque reservado, analytics de recusa.Motivos comuns: saldo insuficiente, cartão bloqueado/vencido, dados inválidos, suspeita de fraude pelo emissor.Aplicável a: cartão de crédito, PIX Recorrente (cobranças automáticas).
PIX Recorrente: com retry_policy = true, o sistema tenta cobrar novamente (até 3 tentativas).
Disparado quando um pagamento expira sem ser completado.Quando usar: liberar estoque reservado, cancelar o pedido, reengajar com novo link.Aplicável a: boleto (após vencimento), PIX (após validade), PIX Recorrente (QR inicial não pago).
Disparado quando uma suspeita de fraude é identificada no pagamento.Quando usar: bloquear o fulfillment, acionar revisão antifraude, registrar a ocorrência.Aplicável a: cartão de crédito.

​
Cancelamento e atualização

Disparado quando um pagamento é cancelado (ex.: cancelamento de uma pré-autorização ou de um pagamento ainda não capturado).Quando usar: liberar o pedido/estoque, registrar o cancelamento.Aplicável a: cartão de crédito.
Disparado quando o cancelamento é confirmado pelo adquirente.Quando usar: dar o cancelamento como concluído com segurança (é o evento final do cancelamento).Aplicável a: cartão de crédito.
Disparado quando o adquirente recusa o cancelamento.Quando usar: manter o pedido no estado anterior e tratar manualmente — o cancelamento não ocorreu.Aplicável a: cartão de crédito.
Disparado quando um pagamento é atualizado (mudança de status ou de dados relevantes ao longo do ciclo).Quando usar: sincronizar o estado do pagamento no seu sistema. Como a ordem de entrega não é garantida, ao receber este evento reconsulte GET /payments/{id} para o estado atual.Aplicável a: todos os métodos.

​
Estornos

Disparado quando um estorno é solicitado e está em processamento. Ocorre antes da confirmação final.Quando usar: informar que o estorno está em andamento, atualizar o status interno.
Disparado quando um estorno é concluído e o valor foi devolvido. É o evento final do estorno.Quando usar: marcar o pedido como estornado, notificar o cliente, ajustar estoque, registros contábeis.
Disparado quando uma solicitação de estorno é negada.Quando usar: notificar a equipe, registrar o motivo, avaliar ação manual (ex.: prazo de estorno esgotado).

​
Chargebacks e disputas

Disparado quando o cliente abre uma disputa (chargeback) junto ao banco.Quando usar: alertar a equipe imediatamente, reunir documentação de defesa, registrar a ocorrência.
Ação urgente. O prazo para contestar costuma ser curto (7–10 dias). Configure alertas para este evento.
Disparado quando há uma atualização na disputa de chargeback.Quando usar: acompanhar o status da disputa, preparar documentação adicional se solicitado.

​
Eventos de Assinatura

Disparado quando uma nova assinatura é criada.Quando usar: registrar a assinatura, liberar acesso inicial, enviar boas-vindas, ativar o trial (se aplicável).
Disparado quando uma assinatura é atualizada (plano, valor da próxima cobrança, método, ciclo).Quando usar: sincronizar a mudança, ajustar o nível de acesso, notificar o cliente.
Disparado quando uma assinatura é cancelada/inativada.Quando usar: bloquear o acesso do cliente ao serviço, notificar o cancelamento, oferecer reativação, analytics de churn.Motivos comuns: cancelamento solicitado pelo cliente, cancelamento por suporte.

​
A vida da assinatura, estado a estado

Cada mudança de estado da assinatura emite o seu próprio evento. Assine os que representam decisão do seu lado (liberar, bloquear, cobrar de novo):
A assinatura passou a estar ativa — na primeira cobrança aprovada, ou ao se recuperar de um atraso/inadimplência.Quando usar: liberar (ou restaurar) o acesso do cliente.
Uma cobrança falhou e a assinatura entrou em atraso. A plataforma tenta cobrar de novo automaticamente nos dias seguintes.Quando usar: avisar o cliente para atualizar o cartão. Não bloqueie o acesso ainda — a recuperação é comum nesta fase.
As retentativas não resolveram e a assinatura ficou inadimplente. Ainda dá para recuperar: pagando, ela volta a ficar ativa.Quando usar: restringir o acesso e escalar a régua de cobrança.
A assinatura foi cancelada. Se o período já pago ainda não terminou, o cliente mantém o acesso até o fim dele e a assinatura pode ser reativada.Quando usar: agendar o fim do acesso, disparar retenção, registrar churn.
A assinatura chegou ao fim — o período pago terminou, ou uma devolução total/chargeback a encerrou.Quando usar: bloquear o acesso definitivamente. É o fim de linha.
A assinatura cumpriu todos os ciclos contratados (planos com número de ciclos definido).Quando usar: encerrar o acesso como conclusão bem-sucedida, oferecer renovação.
O plano da assinatura foi trocado. A mudança vale a partir da próxima renovação.Quando usar: ajustar o nível de acesso do cliente na virada do ciclo.
A cobrança de um ciclo foi aprovada.Quando usar: registrar o pagamento do ciclo e estender o acesso. Cada ciclo também gera os eventos de pagamento (payment.*) da cobrança correspondente.
A cobrança de um ciclo falhou.Quando usar: acompanhar a régua de retentativas. Uma falha isolada não cancela a assinatura — acompanhe subscription.past_due e subscription.unpaid para a decisão de acesso.
A consulta de uma assinatura por API está disponível em GET /subscriptions/{uuid} — use-a para auditar status, ciclo atual e data da próxima cobrança a qualquer momento.

​
PIX Recorrente — quais eventos chegam

O ciclo interno do PIX Recorrente tem etapas de agendamento e envio, mas para o seu webhook chegam apenas os eventos de resultado:
  • Primeira cobrança: payment.authorized (mandato criado / cobrança aprovada) ou payment.refused.
  • Cobranças seguintes: payment.capture_confirmed (sucesso) ou payment.capture_failed / payment.refused (falha).
  • Expiração do QR inicial: payment.expired.
Os passos internos de agendamento/envio (dias antes da cobrança) não geram webhook. Se precisa acompanhar a agenda, use a consulta da assinatura (GET /subscriptions/{uuid}).

​
Configurando eventos na Dashboard

1

Acesse a Dashboard

Faça login em dash.autorizou.com.br
2

Vá até Webhooks

Menu lateral: Integrações → Webhooks
3

Criar ou editar webhook

Ao criar/editar, você verá os eventos organizados por categoria
4

Selecione os eventos

Marque apenas os eventos que você precisa processar
Os eventos aparecem na Dashboard com nomes em português; o valor técnico enviado no webhook é sempre o formato em inglês (ex.: payment.authorized).

​
Eventos recomendados por tipo de negócio

​
E-commerce

  • payment.created — registrar início do pagamento
  • payment.authorized — liberar o pedido para separação
  • payment.refused — notificar o cliente e liberar estoque
  • payment.expired — cancelar o pedido e liberar estoque
  • payment.refunded — processar devolução
  • payment.chargeback_requested — alertar a equipe antifraude

​
Marketplace

  • payment.created — notificar o vendedor
  • payment.authorized — confirmar a venda
  • payment.refused — notificar as partes
  • payment.refunded — estornar e ajustar o saldo do vendedor
  • payment.chargeback_requested — alertar vendedor e plataforma

​
SaaS / Assinaturas

  • payment.authorized — confirmar a renovação
  • payment.capture_confirmed — confirmar a cobrança recorrente (PIX Recorrente)
  • payment.refused — tentar recuperação ou pausar o acesso
  • subscription.created — liberar acesso inicial
  • subscription.updated — ajustar o nível de acesso (upgrade/downgrade)
  • subscription.inactivated — bloquear o acesso ao serviço

​
Serviços digitais (entrega imediata)

  • payment.created — preparar o conteúdo
  • payment.authorized — liberar o acesso
  • payment.refused — notificar o cliente
  • payment.refunded — revogar o acesso

​
Frequência e volume

A quantidade de webhooks depende do seu volume:
  • 1 payment.created por pagamento
  • 1 payment.authorized ou payment.refused por tentativa
  • eventos adicionais conforme o ciclo (captura, estorno, chargeback)
Exemplo: 1.000 vendas/dia ≈ 2.000–3.000 webhooks/dia.

​
Próximos passos

Ver estrutura dos payloads

Entenda o formato dos dados recebidos em cada evento