Eventos

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.

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

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 e seus payloads não têm expiração automática. Eles permanecem disponíveis para consulta, auditoria e debug. Veja Entrega de webhooks para o formato de entrega e Tipos de evento para a lista completa de type.

Objeto event

{
  "id": "evt_Ut77rK2FwFeMLfdB",
  "object": "event",
  "created_at": "2026-05-27T14:09:27Z",
  "data": {
    "object": {
      "id": "cus_cEYDzrzgiujtJgP8",
      "object": "customer",
      "billing_address": null,
      "billing_name": null,
      "created_at": "2026-05-27T14:09:20Z",
      "document": null,
      "document_type": null,
      "email": "nome@email.com",
      "livemode": true,
      "metadata": {},
      "name": "Cliente",
      "phone": null,
      "updated_at": "2026-05-27T14:09:27Z"
    },
    "previous_attributes": {
      "name": "Nome anterior"
    }
  },
  "livemode": true,
  "organization": "org_MBVAu8kJPojfNsjC",
  "request": {
    "id": "req_PPRDuaYhS9HzCWMK"
  },
  "type": "customer.updated"
}

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.

string

Sempre event.

string

Timestamp ISO 8601 de quando o acontecimento foi registrado.

object

Contém o objeto afetado e, em eventos de atualização, o que mudou.

Show Atributos de data

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.

object

Presente quando o evento registra um diff, como eventos .updated e algumas transições de estado. Traz somente os campos alterados com os valores anteriores. Ausente em eventos de criação.

boolean

true para eventos do ambiente de produção, false para o de teste.

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.

object

Referência à chamada de API que originou o evento, quando aplicável.

Show Atributos de request

string | null

ID do request (req_*), ou null para eventos gerados pelo sistema.

string

Tipo do evento, ex.: customer.updated. Veja a lista completa.

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.

Catálogo de eventos

Todos os tipos públicos e links para os payloads individuais.

Entrega e assinatura

Headers, timeout, retries, duplicação, ordem e fan-out.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Como usar

Objeto event

Event vs entrega de webhook

Catálogo de eventos

Entrega e assinatura

​Como usar

​Objeto event

​Event vs entrega de webhook

Catálogo de eventos

Entrega e assinatura

Como usar

Objeto event

Event vs entrega de webhook