> ## 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.

# Overview

> O objeto Event

Um `event` registra algo que aconteceu em um recurso da sua conta: um cliente
foi criado, uma cobrança foi aprovada, uma assinatura foi cancelada.

Cada acontecimento gera **um** event. Esse event existe independente de você ter
endpoints de webhook configurados. Se houver endpoints inscritos, a Chargefy cria
entregas separadas para cada endpoint; se não houver, o event continua disponível
para consulta pela API.

Use events para conciliar o estado do seu sistema com a Chargefy. Use entregas de
webhook para debugar envio, retry, status HTTP e resposta do seu endpoint.

<Info>
  `event` e entrega de webhook são coisas diferentes. O event é o acontecimento;
  a entrega é uma tentativa de enviar esse acontecimento para um endpoint.
</Info>

## Como usar

| Preciso...                      | Use                         |
| ------------------------------- | --------------------------- |
| Saber o que aconteceu           | `type`                      |
| Processar sem duplicar trabalho | `id` do event               |
| Ler o recurso no estado atual   | `data.object`               |
| Saber o que mudou em um update  | `data.previous_attributes`  |
| Saber de qual organização veio  | `organization`              |
| Investigar falha de envio HTTP  | logs de entrega em Webhooks |

Events ficam disponíveis por 30 dias. Depois desse período, eles deixam de
aparecer nas consultas.

Veja [Webhooks](/api-reference/events/webhooks) para o formato de entrega e
[Tipos de evento](/api-reference/webhook-events/types) para a lista completa de
`type`.

## Objeto event

<ResponseExample>
  ```json theme={}
  {
    "id": "evt_123",
    "object": "event",
    "created_at": "2026-05-27T14:09:27Z",
    "data": {
      "object": {
        "id": "cus_123",
        "object": "customer",
        "created_at": "2026-05-27T14:09:20Z",
        "email": "nome@email.com",
        "livemode": true,
        "metadata": {},
        "name": "Cliente"
      },
      "previous_attributes": {
        "name": "Nome anterior"
      }
    },
    "livemode": true,
    "organization": "org_123",
    "request": {
      "id": "req_123"
    },
    "type": "customer.updated"
  }
  ```
</ResponseExample>

<ResponseField name="id" type="string">
  ID único do event (`evt_*`). Use esse valor como chave de idempotência no seu
  sistema: se o mesmo event chegar mais de uma vez por retry, processe apenas
  uma vez.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `event`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp ISO 8601 de quando o acontecimento foi registrado.
</ResponseField>

<ResponseField name="data" type="object">
  Contém o objeto afetado e, em eventos de atualização, o que mudou.

  <Expandable title="Atributos de data">
    <ResponseField name="object" type="object">
      Objeto público completo no estado em que ficou após o acontecimento. O
      campo `object` aninhado identifica o tipo do recurso e `id` é o ID público
      dele.
    </ResponseField>

    <ResponseField name="previous_attributes" type="object">
      Presente apenas em eventos de atualização: traz somente os campos alterados
      com os valores **anteriores**. Ausente nos demais eventos.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="livemode" type="boolean">
  `true` para eventos do ambiente de produção, `false` para o de teste.
</ResponseField>

<ResponseField name="organization" type="string | null">
  Organização que originou o evento. Em integrações de plataforma, esse campo
  aponta para a organização conectada onde o acontecimento ocorreu.
</ResponseField>

<ResponseField name="request" type="object">
  Referência à chamada de API que originou o evento, quando aplicável.

  <Expandable title="Atributos de request">
    <ResponseField name="id" type="string | null">
      ID do request (`req_*`), ou `null` para eventos gerados pelo sistema.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="type" type="string">
  Tipo do evento, ex.: `customer.updated`. Veja a
  [lista completa](/api-reference/webhook-events/types).
</ResponseField>

## Event vs entrega de webhook

Um event pode ter zero, uma ou várias entregas:

| Cenário                    | Resultado                                                            |
| -------------------------- | -------------------------------------------------------------------- |
| Nenhum endpoint inscrito   | O event é criado e aparece na API, mas não há entrega.               |
| Um endpoint inscrito       | O event é criado e uma entrega é enviada para esse endpoint.         |
| Vários endpoints inscritos | O event é criado uma vez e cada endpoint recebe sua própria entrega. |

Essa separação evita duplicação no ledger de events. Você lista acontecimentos
em `/v1/events`; você investiga tentativas HTTP nas telas e logs de Webhooks.