Skip to main content
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
  }
}
CampoTipoDescrição
typestringTipo do evento (ex: subscription.active)
idstringUUID único do evento — mesmo valor do header webhook-id. Use para idempotência.
timestampstringData/hora ISO 8601 do evento
dataobjectPayload 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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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",
    "fee_recipient_organization_id": "org_parent_xyz",
    "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

EventoQuando é disparado
checkout.createdNovo checkout criado
checkout.updatedStatus do checkout mudou
customer.createdNovo cliente registrado
customer.updatedDados do cliente atualizados
customer.deletedCliente removido
customer.state_changedEstado do cliente mudou
subscription.createdNova assinatura criada
subscription.activeAssinatura ativada
subscription.updatedAssinatura atualizada
subscription.canceledAssinatura cancelada
subscription.uncanceledCancelamento revertido
subscription.revokedAssinatura revogada
refund.createdReembolso solicitado
refund.updatedStatus do reembolso mudou
product.createdNovo produto criado
product.updatedProduto atualizado
organization.updatedOrganização atualizada
suborganization.createdNova suborganização criada
suborganization.updatedSuborganização atualizada
suborganization.product_updatedProduto de suborg atualizado
suborganization.subscription_createdAssinatura criada em suborg
suborganization.subscription_updatedAssinatura de suborg atualizada
suborganization.subscription_canceledAssinatura de suborg cancelada

​
Próximos Passos

Criar Endpoints

Configure URLs para receber eventos

Delivery & Verificação

Retry automático e verificação HMAC