> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "type": "checkout.created",
  "timestamp": "2026-03-12T10:00:00.000Z",
  "data": {
    "id": "chk_abc123",
    "status": "open",
    "amount": 9900,
    "currency": "BRL",
    "customer_email": "cliente@email.com",
    "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`).

```json theme={null}
{
  "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).

```json theme={null}
{
  "type": "customer.created",
  "timestamp": "2026-03-12T10:00:00.000Z",
  "data": {
    "id": "cus_456",
    "email": "cliente@email.com",
    "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).

```json theme={null}
{
  "type": "customer.state_changed",
  "timestamp": "2026-03-12T10:00:00.000Z",
  "data": {
    "id": "cus_456",
    "email": "cliente@email.com",
    "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

> [!NOTE]
>
> 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).

```json theme={null}
{
  "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).

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

> [card] [Criar Endpoints](https://scaleup-c34c4386.mintlify.site/integrate/webhooks/endpoints.md)
>
> Configure URLs para receber eventos

> [card] [Delivery & Verificação](https://scaleup-c34c4386.mintlify.site/integrate/webhooks/delivery.md)
>
> Retry automático e verificação HMAC


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.