Eventos de webhook

A Chargefy emite um evento sempre que algo relevante acontece: uma cobrança foi aprovada, uma assinatura mudou, um cliente foi criado. O evento é o registro do fato de negócio. A entrega de webhook é só uma das formas de receber esse fato. Isso deixa a integração mais previsível: você escuta acontecimentos importantes para o seu produto, não o caminho técnico que gerou cada um deles.

Um fato, um evento

Um pagamento confirmado gera um único payment.intent.succeeded, mesmo que ele tenha vindo de checkout, link de pagamento ou API.

Zero ou mais entregas

O evento existe mesmo sem endpoint cadastrado. Se houver endpoints inscritos, cada um recebe sua própria entrega assinada.

Debug mais simples

No dashboard, você acompanha tentativas, status HTTP, resposta do endpoint e reenvia para um endpoint específico quando precisar.

Evento não é entrega

Pense em duas camadas:

Camada	O que significa	Onde você usa
Evento	Algo aconteceu com um recurso (`payment.intent.succeeded`, `subscription.updated`).	Para conciliar pedidos, liberar acesso, atualizar status e consultar histórico.
Entrega	Uma tentativa de enviar esse evento para um endpoint de webhook.	Para debugar falha HTTP, ver retries, copiar resposta do endpoint e reenviar.

Um mesmo evento pode ter várias entregas, uma por endpoint. Também pode não ter nenhuma entrega se você ainda não cadastrou webhooks para aquele ambiente. O histórico do evento continua existindo para consulta pela API.

Na prática: use type para decidir o que fazer no seu sistema, use id para idempotência, e use as telas de Webhooks para investigar problemas de entrega.

O que você vê no dashboard

Na área de webhooks do dashboard, cada endpoint mostra atividade recente e cada entrega mostra o status da tentativa. Esse recorte ajuda a responder perguntas operacionais sem abrir logs:

o endpoint recebeu eventos nas últimas horas?
a última tentativa respondeu 2xx, 4xx, 5xx ou timeout?
qual foi o corpo de resposta retornado pelo seu servidor?
para qual endpoint um evento deve ser reenviado?

O evento continua sendo o mesmo. O que muda entre endpoints são as entregas.

O endpoint deve responder 2xx para confirmar recebimento. Respostas fora de 2xx, timeout ou erro de conexão entram como falha de entrega e podem passar por retry.

Qual evento devo escutar?

Escolha eventos pelo resultado de negócio que você precisa sincronizar.

Quero saber quando…	Escute
Um pagamento foi confirmado	`payment.intent.succeeded`
Uma cobrança individual foi capturada	`charge.succeeded`
Uma assinatura mudou de estado	`subscription.updated`
Uma fatura de assinatura foi paga	`invoice.paid`
Um cliente foi criado ou editado	`customer.created`, `customer.updated`
Uma organização conectada mudou	`organization.updated`

Como o `type` é nomeado

O type segue o padrão namespace.action, separado por pontos — nunca por underscore. O namespace identifica o recurso; a ação identifica o que mudou.

payment.intent.succeeded
└────┬─────┘ └───┬───┘
  recurso      ação

Regra	Detalhe
Separador	Sempre `.` (ponto). Nunca `_` dentro do `type`.
Namespace	O recurso, no singular (`customer`, `subscription`, `payment.intent`).
Ação	O verbo no passado (`created`, `updated`, `succeeded`, `canceled`).
Subestados	Fluxos assíncronos usam mais segmentos (`checkout.session.async.payment.succeeded`).

O type é estável: novos eventos podem ser adicionados, mas um type já publicado não é renomeado. Trate type desconhecido como ignorável — assim sua integração não quebra quando o catálogo cresce.

Anatomia do envelope

Todo evento chega no mesmo envelope. O payload do recurso fica sempre em data.object e segue o mesmo objeto público retornado pela API.

{
  "id": "evt_123",
  "object": "event",
  "created_at": "2026-05-16T14:09:27Z",
  "data": {
    "object": {
      "id": "pi_123",
      "object": "payment_intent",
      "status": "succeeded"
    }
  },
  "livemode": true,
  "organization": "org_123",
  "request": {
    "id": "req_123"
  },
  "type": "payment.intent.succeeded"
}

Campo	Tipo	Descrição
`id`	`string`	ID único do evento; é o mesmo valor do header `webhook-id`.
`object`	`string`	Sempre `event`.
`created_at`	`string`	Data/hora ISO 8601 do evento.
`data.object`	`object`	Objeto público completo no estado atual.
`data.previous_attributes`	`object`	Só em eventos `.updated` (e ações que alteram estado). Veja abaixo.
`livemode`	`boolean`	`true` para eventos do modo live; `false` para modo de teste.
`organization`	`string`	Organização que originou o evento. Em fan-out para plataforma, é a organização conectada filha.
`request.id`	`string`	Request (`req_*`) que originou o evento, quando disponível.
`type`	`string`	Tipo do evento no formato `namespace.action`.

Eventos `.updated` carregam `previous_attributes`

Quando um recurso muda, o evento <recurso>.updated traz data.previous_attributes com apenas os campos que mudaram e seus valores anteriores. O data.object continua sendo o estado atual completo.

{
  "data": {
    "object": {
      "id": "cus_123",
      "object": "customer",
      "email": "novo@email.com"
    },
    "previous_attributes": {
      "email": "antigo@email.com"
    }
  },
  "type": "customer.updated"
}

A resposta direta de um update via API não traz diff — retorna só o objeto atualizado. Quem precisa saber o que mudou lê previous_attributes no webhook .updated. Eventos .created e ações de transição (.succeeded, .canceled) não trazem previous_attributes.

Catálogo de eventos

Os eventos abaixo são agrupados por recurso. Cada nome leva ao schema completo do payload na referência da API.

Customers

Evento	Quando dispara
`customer.created`	Um cliente é criado.
`customer.updated`	Um campo do cliente muda (traz `previous_attributes`).
`customer.deleted`	Um cliente é removido.

Products

Evento	Quando dispara
`product.created`	Um produto é criado.
`product.updated`	Um campo do produto muda, inclusive `is_active=false` ao arquivar (traz `previous_attributes`).

Prices

Evento	Quando dispara
`price.created`	Um preço é criado e atrelado a um produto.
`price.updated`	Um campo editável do preço muda, inclusive `is_active=false` ao arquivar (traz `previous_attributes`).

Payment Intents

A família payment.intent.* cobre todo mode=payment one-shot — cartão, PIX e boleto. Métodos assíncronos (PIX e boleto) ficam pendentes até o pagamento ser confirmado; aí emitem payment.intent.succeeded. Boletos não pagos até expires_at viram payment.intent.canceled com cancellation_reason: "abandoned" automaticamente.

Evento	Quando dispara
`payment.intent.created`	Uma intenção de pagamento é aberta.
`payment.intent.updated`	A intenção muda de estado ou tem campos atualizados (traz `previous_attributes`).
`payment.intent.succeeded`	O pagamento é confirmado.
`payment.intent.failed`	A tentativa de pagamento falha.
`payment.intent.canceled`	A intenção é cancelada ou expira sem pagamento.

Charges

Evento	Quando dispara
`charge.succeeded`	Uma cobrança individual é capturada com sucesso.
`charge.failed`	Uma cobrança individual é recusada.
`charge.updated`	Um campo da cobrança muda (traz `previous_attributes`).
`charge.refunded`	Uma cobrança recebe um refund parcial ou total.

Disputes

Evento	Quando dispara
`charge.dispute.created`	Uma contestação é criada para uma cobrança.
`charge.dispute.updated`	A contestação muda de estado ou evidência.
`charge.dispute.closed`	A contestação recebe uma decisão final como `won` ou `lost`.

Refunds

Evento	Quando dispara
`refund.created`	Um refund é criado.
`refund.failed`	Um refund chega ao estado `failed`.
`refund.updated`	Um refund muda de estado (traz `previous_attributes`).

Receivables

Evento	Quando dispara
`receivable.created`	Um receivable é gerado para uma venda confirmada.
`receivable.paid`	Um receivable é liquidado (traz `previous_attributes`).
`receivable.canceled`	Um receivable é cancelado antes da liquidação (traz `previous_attributes`).
`receivable.refunded`	Um receivable é revertido por estorno (traz `previous_attributes`).

Payment Methods

Evento	Quando dispara
`payment.method.created`	Um meio de pagamento é criado.
`payment.method.updated`	Um campo do meio de pagamento muda (traz `previous_attributes`).
`payment.method.attached`	Um meio de pagamento é vinculado a um cliente.
`payment.method.detached`	Um meio de pagamento é desvinculado de um cliente.

Setup Intents

Um setup intent guarda um meio de pagamento para uso futuro, sem cobrar agora.

Evento	Quando dispara
`setup.intent.created`	Uma intenção de cadastro de meio de pagamento é aberta.
`setup.intent.succeeded`	O meio de pagamento é validado e guardado com sucesso.
`setup.intent.failed`	A validação do meio de pagamento falha.
`setup.intent.canceled`	A intenção de cadastro é cancelada.

Checkout Sessions

Evento	Quando dispara
`checkout.session.created`	Uma sessão de checkout é aberta.
`checkout.session.completed`	O comprador conclui o checkout.
`checkout.session.async.payment.succeeded`	O pagamento assíncrono (PIX/boleto) da sessão é confirmado.
`checkout.session.async.payment.failed`	O pagamento assíncrono da sessão falha.
`checkout.session.expired`	A sessão expira sem conclusão.

Payment Links

Evento	Quando dispara
`payment.link.created`	Um link de pagamento é criado.
`payment.link.updated`	Um campo do link muda, inclusive `is_active=false` ao desativar (traz `previous_attributes`).

Invoices

Invoices representam cobranças de assinatura por padrão. Compras avulsas só geram invoice quando a sessão foi criada com invoice_creation=true — caso contrário, escute payment.intent.succeeded. Trials emitem invoice.paid para a invoice de R$ 0 que registra o período.

Evento	Quando dispara
`invoice.created`	Uma invoice é criada e fica pronta para cobrança.
`invoice.paid`	A invoice é paga.
`invoice.payment.failed`	Uma tentativa de cobrança da invoice falha.
`invoice.voided`	A invoice é anulada (`void`).

Subscriptions

Evento	Quando dispara
`subscription.created`	Uma assinatura é criada.
`subscription.updated`	Um campo da assinatura muda (traz `previous_attributes`).
`subscription.canceled`	A assinatura é cancelada.
`subscription.paused`	A assinatura é pausada.
`subscription.resumed`	A assinatura volta da pausa.
`subscription.trial.will.end`	O trial está perto de terminar.
`subscription.pending.update.applied`	Uma pending update é aplicada.
`subscription.pending.update.expired`	Uma pending update expira.

Organizations

Eventos do contexto de plataforma: a organização conectada que origina o evento vai em organization.

Evento	Quando dispara
`organization.created`	Uma organização conectada é criada.
`organization.updated`	Um campo da organização conectada muda (traz `previous_attributes`).

Organization Reviews

Evento	Quando dispara
`organization.review.required`	Uma organização conectada precisa confirmar ou atualizar dados cadastrais.
`organization.review.submitted`	O formulário hospedado de atualização cadastral é enviado para análise.

Onboarding Sessions

Evento	Quando dispara
`onboarding.session.submitted`	A onboarding session de uma organização conectada é enviada para análise.

Eventos de webhook

Um fato, um evento

Zero ou mais entregas

Debug mais simples

Evento não é entrega

O que você vê no dashboard

Qual evento devo escutar?

Como o `type` é nomeado

Anatomia do envelope

Eventos `.updated` carregam `previous_attributes`

Catálogo de eventos

Customers

Products

Prices

Payment Intents

Charges

Disputes

Refunds

Receivables

Payment Methods

Setup Intents

Checkout Sessions

Payment Links

Invoices

Subscriptions

Organizations

Organization Reviews

Onboarding Sessions

Próximos passos

Entrega e assinatura

Objeto event

Um fato, um evento

Zero ou mais entregas

Debug mais simples

​Evento não é entrega

​O que você vê no dashboard

​Qual evento devo escutar?

​Como o type é nomeado

​Anatomia do envelope

​Eventos .updated carregam previous_attributes

​Catálogo de eventos

​Customers

​Products

​Prices

​Payment Intents

​Charges

​Disputes

​Refunds

​Receivables

​Payment Methods

​Setup Intents

​Checkout Sessions

​Payment Links

​Invoices

​Subscriptions

​Organizations

​Organization Reviews

​Onboarding Sessions

​Próximos passos

Entrega e assinatura

Objeto event

Evento não é entrega

O que você vê no dashboard

Qual evento devo escutar?

Como o `type` é nomeado

Anatomia do envelope

Eventos `.updated` carregam `previous_attributes`

Catálogo de eventos

Customers

Products

Prices

Payment Intents

Charges

Disputes

Refunds

Receivables

Payment Methods

Setup Intents

Checkout Sessions

Payment Links

Invoices

Subscriptions

Organizations

Organization Reviews

Onboarding Sessions

Próximos passos