Webhook Events

Lista completa de eventos de webhook disponíveis na Chargefy

A Chargefy emite eventos que você pode receber via webhooks. Cada evento contém um payload com os dados relevantes do recurso afetado.

​

Estrutura do Payload

Todos os webhooks seguem o mesmo formato:

{
  "type": "subscription.active",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-12T10:30:00.000Z",
  "data": {
    // Dados específicos do evento
  }
}

Campo	Tipo	Descrição
type	string	Tipo do evento (ex: subscription.active)
id	string	UUID único do evento — mesmo valor do header webhook-id. Use para idempotência.
timestamp	string	Data/hora ISO 8601 do evento
data	object	Payload com os dados do recurso

​

Eventos de Checkout

Emitidos durante o fluxo de pagamento.

​

checkout.created

Disparado quando um novo checkout é criado.

{
  "type": "checkout.created",
  "timestamp": "2026-03-12T10:00:00.000Z",
  "data": {
    "id": "chk_abc123",
    "status": "open",
    "amount": 9900,
    "currency": "BRL",
    "customer_email": "[e-mail]",
    "product_id": "prod_123",
    "organization_id": "org_123",
    "created_at": "2026-03-12T10:00:00.000Z"
  }
}

​

checkout.updated

Disparado quando o status de um checkout muda (ex: open → confirmed → succeeded).

{
  "type": "checkout.updated",
  "timestamp": "2026-03-12T10:05:00.000Z",
  "data": {
    "id": "chk_abc123",
    "status": "succeeded",
    "payment_method": "pix",
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "cus_456",
    "product_id": "prod_123",
    "organization_id": "org_123"
  }
}

​

Eventos de Cliente

Emitidos quando clientes são criados ou atualizados.

​

customer.created

Disparado quando um novo cliente é criado (geralmente via checkout).

{
  "type": "customer.created",
  "timestamp": "2026-03-12T10:00:00.000Z",
  "data": {
    "id": "cus_456",
    "email": "[e-mail]",
    "name": "João Silva",
    "organization_id": "org_123",
    "created_at": "2026-03-12T10:00:00.000Z"
  }
}

​

customer.updated

Disparado quando os dados de um cliente são atualizados.

​

customer.deleted

Disparado quando um cliente é removido.

​

customer.state_changed

Disparado quando o estado do cliente muda (ex: ativação ou cancelamento de assinatura).

{
  "type": "customer.state_changed",
  "timestamp": "2026-03-12T10:00:00.000Z",
  "data": {
    "id": "cus_456",
    "email": "[e-mail]",
    "active_subscriptions": ["sub_789"]
  }
}

​

Eventos de Assinatura (Subscription)

Emitidos durante o ciclo de vida de assinaturas recorrentes.

​

subscription.created

Disparado quando uma nova assinatura é criada.

{
  "type": "subscription.created",
  "timestamp": "2026-03-12T10:05:00.000Z",
  "data": {
    "id": "sub_789",
    "status": "active",
    "customer_id": "cus_456",
    "product_id": "prod_123",
    "price_id": "price_456",
    "current_period_start": "2026-03-12T00:00:00.000Z",
    "current_period_end": "2026-04-12T00:00:00.000Z",
    "recurring_interval": "month"
  }
}

​

subscription.active

Disparado quando uma assinatura se torna ativa (após pagamento da primeira cobrança ou reativação).

​

subscription.updated

Disparado quando os dados de uma assinatura são atualizados (ex: mudança de plano).

​

subscription.canceled

Disparado quando uma assinatura é cancelada pelo cliente ou administrador.

{
  "type": "subscription.canceled",
  "timestamp": "2026-03-12T15:00:00.000Z",
  "data": {
    "id": "sub_789",
    "status": "canceled",
    "customer_id": "cus_456",
    "cancel_at_period_end": true,
    "canceled_at": "2026-03-12T15:00:00.000Z",
    "current_period_end": "2026-04-12T00:00:00.000Z"
  }
}

​

subscription.uncanceled

Disparado quando o cancelamento de uma assinatura é revertido antes do fim do período.

​

subscription.revoked

Disparado quando uma assinatura é revogada imediatamente (sem aguardar fim do período).

​

Eventos de Reembolso (Refund)

​

refund.created

Disparado quando um reembolso é solicitado.

​

refund.updated

Disparado quando o status de um reembolso muda (ex: processado, falhou).

​

Eventos de Produto (Product)

​

product.created

Disparado quando um novo produto é criado.

​

product.updated

Disparado quando os dados de um produto são atualizados.

​

Eventos de Organização

​

organization.updated

Disparado quando os dados da organização são atualizados.

​

Eventos de Suborganização

Estes eventos são enviados para a organização pai (marketplace) quando há atividade em suas organizações filhas (suborganizações). Use-os para monitorar vendas, assinaturas e produtos das suborganizações.

Todos os eventos de suborganização incluem data.parent_organization_id — o ID da organização pai que recebeu o webhook. Campos internos do gateway de pagamento são expostos com o prefixo gateway_ (ex: gateway_subscription_id).

​

suborganization.created

Disparado quando uma nova suborganização é criada pelo pai (via SDK).

{
  "type": "suborganization.created",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-18T12:00:00.000Z",
  "data": {
    "suborganization": {
      "id": "org_child_abc123",
      "name": "Suborg LTDA",
      "slug": "suborg-ltda",
      "status": "created"
    },
    "parent_organization_id": "org_parent_xyz"
  }
}

​

suborganization.updated

Disparado quando uma suborganização é atualizada.

Em um caso adicional, assíncrono: ao criar uma suborganização que reutiliza um seller do gateway já existente (mesmo CPF/CNPJ), a API consulta o seller no processador após a criação. Se o seller estiver com status active, ou (caso contrário) se a API de documentos KYC não indicar uploads pendentes, a suborganização é marcada como active no banco e este evento é enviado aos pais — sem alterar a resposta 201 do endpoint de criação (o cliente pode ainda receber status: "created" no corpo imediato).

{
  "type": "suborganization.updated",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "timestamp": "2026-03-18T12:00:00.000Z",
  "data": {
    "suborganization": {
      "id": "org_child_abc123",
      "name": "Suborg LTDA Atualizada",
      "slug": "suborg-ltda",
      "status": "active",
      "modified_at": "2026-03-18T12:00:00.000Z"
    },
    "parent_organization_id": "org_parent_xyz"
  }
}

​

suborganization.product_updated

Disparado quando um produto de uma suborganização é atualizado.

{
  "type": "suborganization.product_updated",
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "timestamp": "2026-03-18T12:00:00.000Z",
  "data": {
    "id": "prod_abc123",
    "name": "Plano Pro",
    "organization_id": "org_child_abc123",
    "status": "active",
    "parent_organization_id": "org_parent_xyz"
  }
}

​

suborganization.subscription_created

Disparado quando uma assinatura é criada em um produto de uma suborganização.

{
  "type": "suborganization.subscription_created",
  "id": "550e8400-e29b-41d4-a716-446655440004",
  "timestamp": "2026-03-18T12:00:00.000Z",
  "data": {
    "checkout_id": "chk_abc123",
    "customer_id": "cus_456",
    "product_id": "prod_xyz",
    "organization_id": "org_child_abc123",
    "status": "active",
    "gateway_subscription_id": "sub_gateway_789",
    "parent_organization_id": "org_parent_xyz"
  }
}

​

suborganization.subscription_updated

Disparado quando uma assinatura de uma suborganização é atualizada.

{
  "type": "suborganization.subscription_updated",
  "id": "550e8400-e29b-41d4-a716-446655440005",
  "timestamp": "2026-03-18T12:00:00.000Z",
  "data": {
    "id": "sub_abc123",
    "organization_id": "org_child_abc123",
    "customer_id": "cus_456",
    "status": "active",
    "current_period_end": "2026-04-01T00:00:00.000Z",
    "parent_organization_id": "org_parent_xyz"
  }
}

​

suborganization.subscription_canceled

Disparado quando uma assinatura de uma suborganização é cancelada.

{
  "type": "suborganization.subscription_canceled",
  "id": "550e8400-e29b-41d4-a716-446655440006",
  "timestamp": "2026-03-18T12:00:00.000Z",
  "data": {
    "id": "sub_abc123",
    "organization_id": "org_child_abc123",
    "customer_id": "cus_456",
    "status": "canceled",
    "cancel_at_period_end": true,
    "canceled_at": "2026-03-18T12:00:00.000Z",
    "current_period_end": "2026-04-01T00:00:00.000Z",
    "parent_organization_id": "org_parent_xyz"
  }
}

​

Tabela Resumo

Evento	Quando é disparado
checkout.created	Novo checkout criado
checkout.updated	Status do checkout mudou
customer.created	Novo cliente registrado
customer.updated	Dados do cliente atualizados
customer.deleted	Cliente removido
customer.state_changed	Estado do cliente mudou
subscription.created	Nova assinatura criada
subscription.active	Assinatura ativada
subscription.updated	Assinatura atualizada
subscription.canceled	Assinatura cancelada
subscription.uncanceled	Cancelamento revertido
subscription.revoked	Assinatura revogada
refund.created	Reembolso solicitado
refund.updated	Status do reembolso mudou
product.created	Novo produto criado
product.updated	Produto atualizado
organization.updated	Organização atualizada
suborganization.created	Nova suborganização criada
suborganization.updated	Suborganização atualizada
suborganization.product_updated	Produto de suborg atualizado
suborganization.subscription_created	Assinatura criada em suborg
suborganization.subscription_updated	Assinatura de suborg atualizada
suborganization.subscription_canceled	Assinatura de suborg cancelada

​

Próximos Passos

Criar Endpoints

Configure URLs para receber eventos

Delivery & Verificação

Retry automático e verificação HMAC