Eventos

{
  "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": "[email protected]",
      "livemode": true,
      "metadata": {},
      "name": "Cliente",
      "phone": null,
      "trade_name": null,
      "updated_at": "2026-05-27T14:09:27Z"
    },
    "previous_attributes": {
      "name": "Nome anterior"
    }
  },
  "livemode": true,
  "organization": "org_MBVAu8kJPojfNsjC",
  "pending_webhooks": 1,
  "request": {
    "id": "req_PPRDuaYhS9HzCWMK"
  },
  "type": "customer.updated",
  "webhook_deliveries": [
    {
      "attempted_at": "2026-05-27T14:39:31Z",
      "http_code": 500,
      "status": "failed",
      "webhook_endpoint": "we_9wQpX3sT7mK2rV5L"
    }
  ]
}

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. Para saber se um event chegou aos seus endpoints, leia pending_webhooks e webhook_deliveries no próprio event, ou filtre a listagem com delivery_success=false. O corpo da resposta do seu endpoint e cada tentativa individual ficam nos logs de entrega em Webhooks.

event e entrega de webhook são coisas diferentes. O event é o acontecimento; a entrega é uma tentativa de enviar esse acontecimento para um endpoint. A API devolve o event com um resumo do estado de entrega; o payload entregue ao seu endpoint não carrega esse resumo.

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`
Saber se o event chegou ao meu endpoint	`pending_webhooks` e `webhook_deliveries`
Encontrar events que não foram entregues	`GET /v1/events?delivery_success=false`
Investigar falha de envio HTTP	`webhook_deliveries[].http_code` e 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": "[email protected]",
      "livemode": true,
      "metadata": {},
      "name": "Cliente",
      "phone": null,
      "trade_name": null,
      "updated_at": "2026-05-27T14:09:27Z"
    },
    "previous_attributes": {
      "name": "Nome anterior"
    }
  },
  "livemode": true,
  "organization": "org_MBVAu8kJPojfNsjC",
  "pending_webhooks": 1,
  "request": {
    "id": "req_PPRDuaYhS9HzCWMK"
  },
  "type": "customer.updated",
  "webhook_deliveries": [
    {
      "attempted_at": "2026-05-27T14:39:31Z",
      "http_code": 500,
      "status": "failed",
      "webhook_endpoint": "we_9wQpX3sT7mK2rV5L"
    }
  ]
}

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.

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

integer

Quantidade de endpoints de webhook que ainda não receberam este event: a última tentativa falhou (resposta fora de 2xx ou sem resposta) e não foi descartada. 0 quando todos os endpoints responderam 2xx ou quando não há endpoint inscrito. Uma sequência de events com pending_webhooks acima de zero significa que o seu endpoint está falhando.

object

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

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

array

Última tentativa de entrega para cada endpoint de webhook inscrito. Lista vazia quando nenhum endpoint recebeu este event ainda ou quando não há endpoint inscrito.

Mostrar Atributos de webhook_deliveries[]

string

Timestamp ISO 8601 da última tentativa.

integer | null

Status HTTP que o endpoint respondeu. null quando a requisição não chegou a ser enviada (timeout de conexão, DNS, assinatura).

string

delivered quando o endpoint respondeu 2xx; failed quando respondeu fora de 2xx ou não respondeu (a reentrega automática continua por cerca de 3 dias e depois o estado permanece failed); discarded quando o endpoint foi pausado, removido ou deixou de ser elegível, sem novas tentativas.

string

ID do endpoint (we_*).

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.

{
  "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": "[email protected]",
      "livemode": true,
      "metadata": {},
      "name": "Cliente",
      "phone": null,
      "trade_name": null,
      "updated_at": "2026-05-27T14:09:27Z"
    },
    "previous_attributes": {
      "name": "Nome anterior"
    }
  },
  "livemode": true,
  "organization": "org_MBVAu8kJPojfNsjC",
  "pending_webhooks": 1,
  "request": {
    "id": "req_PPRDuaYhS9HzCWMK"
  },
  "type": "customer.updated",
  "webhook_deliveries": [
    {
      "attempted_at": "2026-05-27T14:39:31Z",
      "http_code": 500,
      "status": "failed",
      "webhook_endpoint": "we_9wQpX3sT7mK2rV5L"
    }
  ]
}

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

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