> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Eventos de webhook
> Entenda os eventos da Chargefy, como eles viram entregas de webhook e quais fatos de negócio vale escutar.
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 pagamento confirmado gera um único `payment.intent.succeeded`, mesmo que
ele tenha vindo de checkout, link de pagamento ou API.
O evento existe mesmo sem endpoint cadastrado. Se houver endpoints inscritos,
cada um recebe sua própria entrega assinada.
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.
```text theme={}
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.
```json theme={}
{
"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 `.updated` traz `data.previous_attributes` com **apenas os campos que mudaram** e seus **valores anteriores**. O `data.object` continua sendo o estado atual completo.
```json theme={}
{
"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`](/api-reference/webhooks/customer.created) | Um cliente é criado. |
| [`customer.updated`](/api-reference/webhooks/customer.updated) | Um campo do cliente muda (traz `previous_attributes`). |
| [`customer.deleted`](/api-reference/webhooks/customer.deleted) | Um cliente é removido. |
### Products
| Evento | Quando dispara |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| [`product.created`](/api-reference/webhooks/product.created) | Um produto é criado. |
| [`product.updated`](/api-reference/webhooks/product.updated) | Um campo do produto muda, inclusive `is_active=false` ao arquivar (traz `previous_attributes`). |
### Prices
| Evento | Quando dispara |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [`price.created`](/api-reference/webhooks/price.created) | Um preço é criado e atrelado a um produto. |
| [`price.updated`](/api-reference/webhooks/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`](/api-reference/webhooks/payment.intent.created) | Uma intenção de pagamento é aberta. |
| [`payment.intent.updated`](/api-reference/webhooks/payment.intent.updated) | A intenção muda de estado ou tem campos atualizados (traz `previous_attributes`). |
| [`payment.intent.succeeded`](/api-reference/webhooks/payment.intent.succeeded) | O pagamento é confirmado. |
| [`payment.intent.failed`](/api-reference/webhooks/payment.intent.failed) | A tentativa de pagamento falha. |
| [`payment.intent.canceled`](/api-reference/webhooks/payment.intent.canceled) | A intenção é cancelada ou expira sem pagamento. |
### Charges
| Evento | Quando dispara |
| -------------------------------------------------------------- | ------------------------------------------------------- |
| [`charge.succeeded`](/api-reference/webhooks/charge.succeeded) | Uma cobrança individual é capturada com sucesso. |
| [`charge.failed`](/api-reference/webhooks/charge.failed) | Uma cobrança individual é recusada. |
| [`charge.updated`](/api-reference/webhooks/charge.updated) | Um campo da cobrança muda (traz `previous_attributes`). |
| [`charge.refunded`](/api-reference/webhooks/charge.refunded) | Uma cobrança recebe um refund parcial ou total. |
### Disputes
| Evento | Quando dispara |
| -------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [`charge.dispute.created`](/api-reference/webhooks/charge.dispute.created) | Uma contestação é criada para uma cobrança. |
| [`charge.dispute.updated`](/api-reference/webhooks/charge.dispute.updated) | A contestação muda de estado ou evidência. |
| [`charge.dispute.closed`](/api-reference/webhooks/charge.dispute.closed) | A contestação recebe uma decisão final como `won` ou `lost`. |
### Refunds
| Evento | Quando dispara |
| ---------------------------------------------------------- | ------------------------------------------------------ |
| [`refund.created`](/api-reference/webhooks/refund.created) | Um refund é criado. |
| [`refund.failed`](/api-reference/webhooks/refund.failed) | Um refund chega ao estado `failed`. |
| [`refund.updated`](/api-reference/webhooks/refund.updated) | Um refund muda de estado (traz `previous_attributes`). |
### Receivables
| Evento | Quando dispara |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [`receivable.created`](/api-reference/webhooks/receivable.created) | Um receivable é gerado para uma venda confirmada. |
| [`receivable.paid`](/api-reference/webhooks/receivable.paid) | Um receivable é liquidado (traz `previous_attributes`). |
| [`receivable.canceled`](/api-reference/webhooks/receivable.canceled) | Um receivable é cancelado antes da liquidação (traz `previous_attributes`). |
| [`receivable.refunded`](/api-reference/webhooks/receivable.refunded) | Um receivable é revertido por estorno (traz `previous_attributes`). |
### Payment Methods
| Evento | Quando dispara |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [`payment.method.created`](/api-reference/webhooks/payment.method.created) | Um meio de pagamento é criado. |
| [`payment.method.updated`](/api-reference/webhooks/payment.method.updated) | Um campo do meio de pagamento muda (traz `previous_attributes`). |
| [`payment.method.attached`](/api-reference/webhooks/payment.method.attached) | Um meio de pagamento é vinculado a um cliente. |
| [`payment.method.detached`](/api-reference/webhooks/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`](/api-reference/webhooks/setup.intent.created) | Uma intenção de cadastro de meio de pagamento é aberta. |
| [`setup.intent.succeeded`](/api-reference/webhooks/setup.intent.succeeded) | O meio de pagamento é validado e guardado com sucesso. |
| [`setup.intent.failed`](/api-reference/webhooks/setup.intent.failed) | A validação do meio de pagamento falha. |
| [`setup.intent.canceled`](/api-reference/webhooks/setup.intent.canceled) | A intenção de cadastro é cancelada. |
### Checkout Sessions
| Evento | Quando dispara |
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [`checkout.session.created`](/api-reference/webhooks/checkout.session.created) | Uma sessão de checkout é aberta. |
| [`checkout.session.completed`](/api-reference/webhooks/checkout.session.completed) | O comprador conclui o checkout. |
| [`checkout.session.async.payment.succeeded`](/api-reference/webhooks/checkout.session.async.payment.succeeded) | O pagamento assíncrono (PIX/boleto) da sessão é confirmado. |
| [`checkout.session.async.payment.failed`](/api-reference/webhooks/checkout.session.async.payment.failed) | O pagamento assíncrono da sessão falha. |
| [`checkout.session.expired`](/api-reference/webhooks/checkout.session.expired) | A sessão expira sem conclusão. |
### Payment Links
| Evento | Quando dispara |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| [`payment.link.created`](/api-reference/webhooks/payment.link.created) | Um link de pagamento é criado. |
| [`payment.link.updated`](/api-reference/webhooks/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`](/api-reference/webhooks/invoice.created) | Uma invoice é criada e fica pronta para cobrança. |
| [`invoice.paid`](/api-reference/webhooks/invoice.paid) | A invoice é paga. |
| [`invoice.payment.failed`](/api-reference/webhooks/invoice.payment.failed) | Uma tentativa de cobrança da invoice falha. |
| [`invoice.voided`](/api-reference/webhooks/invoice.voided) | A invoice é anulada (`void`). |
### Subscriptions
| Evento | Quando dispara |
| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [`subscription.created`](/api-reference/webhooks/subscription.created) | Uma assinatura é criada. |
| [`subscription.updated`](/api-reference/webhooks/subscription.updated) | Um campo da assinatura muda (traz `previous_attributes`). |
| [`subscription.canceled`](/api-reference/webhooks/subscription.canceled) | A assinatura é cancelada. |
| [`subscription.paused`](/api-reference/webhooks/subscription.paused) | A assinatura é pausada. |
| [`subscription.resumed`](/api-reference/webhooks/subscription.resumed) | A assinatura volta da pausa. |
| [`subscription.trial.will.end`](/api-reference/webhooks/subscription.trial.will.end) | O trial está perto de terminar. |
| [`subscription.pending.update.applied`](/api-reference/webhooks/subscription.pending.update.applied) | Uma pending update é aplicada. |
| [`subscription.pending.update.expired`](/api-reference/webhooks/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`](/api-reference/webhooks/organization.created) | Uma organização conectada é criada. |
| [`organization.updated`](/api-reference/webhooks/organization.updated) | Um campo da organização conectada muda (traz `previous_attributes`). |
### Organization Reviews
| Evento | Quando dispara |
| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [`organization.review.required`](/api-reference/webhooks/organization.review.required) | Uma organização conectada precisa confirmar ou atualizar dados cadastrais. |
| [`organization.review.submitted`](/api-reference/webhooks/organization.review.submitted) | O formulário hospedado de atualização cadastral é enviado para análise. |
### Onboarding Sessions
| Evento | Quando dispara |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [`onboarding.session.submitted`](/api-reference/webhooks/onboarding.session.submitted) | A onboarding session de uma organização conectada é enviada para análise. |
## Próximos passos
Retries, headers e como verificar a assinatura Standard Webhooks.
Veja o shape completo de um payload de evento.