Evento customer.updated

Evento `customer.updated`

Disparado quando campos de um cliente mudam, via POST /v1/customers/:id ou durante o checkout/cobrança automática (ex.: enriquecimento de billing_address ou document). data.object carrega o customer completo no estado atual. data.previous_attributes traz só os campos que mudaram, com os valores anteriores. Use este evento para manter seus dados locais de comprador sincronizados sem perder o estado final. O diff ajuda em auditoria e notificações, mas a fonte principal para persistir é sempre data.object.

Campos ausentes em data.previous_attributes não mudaram naquele evento. Eles continuam disponíveis no customer completo dentro de data.object.

Quando acontece

Situação	Como aparece no payload
Customer atualizado pela API	`data.object.updated_at` recebe o horário da mudança.
Checkout enriquece dados do comprador	Campos como `billing_address`, `phone` ou `document` podem mudar.
Metadata foi alterada	`previous_attributes.metadata` mostra o valor anterior.
Dados de cobrança foram completados	`billing_name` ou `billing_address` aparecem no objeto atual.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Atualize seu registro local usando data.object, que contém o customer completo e atual.
Use data.previous_attributes apenas para auditoria, logs ou notificações condicionais.
Trate null como valor explícito quando o campo puder ser limpo ou ainda não tiver sido informado.
Use metadata para manter a correlação com seu sistema, sem depender de chaves obrigatórias dentro dela.

Campos importantes

Campo	O que observar
`data.object.id`	Customer atualizado.
`data.previous_attributes`	Valores anteriores dos campos públicos que mudaram.
`email`	E-mail atual do customer.
`billing_address`	Endereço de cobrança atual ou `null`.
`phone`	Telefone atual ou `null`.
`metadata`	Objeto livre atual; o diff aparece em `previous_attributes` quando muda.
`updated_at`	Horário da atualização no objeto atual.

Exemplo de payload

{
  "id": "evt_F9xNGH5xp9rBPN5R",
  "object": "event",
  "created_at": "2026-05-16T15:02:10Z",
  "data": {
    "object": {
      "id": "cus_N7PS5d7g9dAJk4MX",
      "object": "customer",
      "billing_address": {
        "city": "São Paulo",
        "country": "BR",
        "line1": "Av. Paulista, 1000",
        "line2": null,
        "postal_code": "01310-100",
        "state": "SP"
      },
      "billing_name": null,
      "created_at": "2026-05-16T14:09:27Z",
      "document": "12345678901",
      "document_type": "cpf",
      "email": "nome@email.com",
      "livemode": true,
      "metadata": {},
      "name": "Cliente Exemplo",
      "phone": "+5511999990000",
      "updated_at": "2026-05-16T15:02:10Z"
    },
    "previous_attributes": {
      "billing_address": null,
      "phone": null
    }
  },
  "livemode": true,
  "organization": "org_DKVicFGHdqyw4oik",
  "request": {
    "id": null
  },
  "type": "customer.updated"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento customer.updated