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

> Configure endpoints para receber notificações em tempo real de eventos da Chargefy

Webhooks permitem que sua aplicação receba notificações HTTP em tempo real quando eventos ocorrem na Chargefy — como pagamentos confirmados, assinaturas criadas ou vendas atualizadas.

## Visão Geral

Quando um evento ocorre na plataforma, a Chargefy envia uma requisição `POST` para as URLs que você configurou, com o payload do evento no corpo da requisição.

```
Chargefy → POST https://seusite.com.br/webhooks/chargefy → Sua aplicação
```

## Criar um Webhook Endpoint

### Via Dashboard

1. Acesse **Configurações** → **Webhooks** no [dashboard](https://chargefy.io)
2. Clique em **Criar Endpoint**
3. Informe a URL (deve ser **HTTPS**)
4. Selecione os eventos que deseja receber
5. Escolha o formato (`raw`, `discord` ou `slack`)
6. Salve — o secret será gerado automaticamente

### Via API

```bash theme={null}
curl -X POST https://api.chargefy.io/api/v1/webhooks/endpoints \
  -H "Authorization: Bearer <supabase_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusite.com.br/webhooks/chargefy",
    "events": [
      "checkout.created",
      "checkout.updated",
      "subscription.active",
      "subscription.created",
      "subscription.canceled"
    ],
    "format": "raw"
  }'
```

```typescript theme={null}
const endpoint = await fetch('https://api.chargefy.io/api/v1/webhooks/endpoints', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.CHARGEFY_ACCESS_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://seusite.com.br/webhooks/chargefy',
    events: [
      'checkout.created',
      'checkout.updated',
      'subscription.active',
      'subscription.created',
      'subscription.canceled'
    ],
    format: 'raw'
  })
});

const { id, secret } = await endpoint.json();
// secret: whsec_... (guarde em local seguro!)
```

### Resposta

```json theme={null}
{
  "id": "wep_abc123",
  "url": "https://seusite.com.br/webhooks/chargefy",
  "format": "raw",
  "secret": "whsec_...",
  "events": [
    "checkout.created",
    "checkout.updated",
    "subscription.active",
    "subscription.created",
    "subscription.canceled"
  ],
  "organization_id": "org_123",
  "created_at": "2026-03-01T10:00:00Z"
}
```

> [!WARNING]
>
> O `secret` só é exibido na criação. Armazene-o em local seguro — você precisará dele para [verificar assinaturas](https://scaleup-c34c4386.mintlify.site/integrate/webhooks/delivery.md).

## Formatos de Webhook

| Formato | Descrição | Uso |
| - | - | - |
| `raw` | Payload JSON padrão | Integrações customizadas |
| `discord` | Formato Discord webhook | Notificações em canais Discord |
| `slack` | Formato Slack webhook | Notificações em canais Slack |

## Gerenciar Endpoints

### Listar Endpoints

```bash theme={null}
curl -X GET https://api.chargefy.io/api/v1/webhooks/endpoints \
  -H "Authorization: Bearer <supabase_jwt>"
```

### Atualizar Endpoint

```bash theme={null}
curl -X PATCH https://api.chargefy.io/api/v1/webhooks/endpoints/{id} \
  -H "Authorization: Bearer <supabase_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["subscription.active", "subscription.canceled"]
  }'
```

### Regenerar Secret

Se o secret for comprometido, você pode regenerá-lo:

```bash theme={null}
curl -X PATCH https://api.chargefy.io/api/v1/webhooks/endpoints/{id}/secret \
  -H "Authorization: Bearer <supabase_jwt>"
```

> [!WARNING]
>
> Após regenerar o secret, atualize imediatamente sua aplicação com o novo valor. Webhooks assinados com o secret antigo falharão na verificação.

### Deletar Endpoint

```bash theme={null}
curl -X DELETE https://api.chargefy.io/api/v1/webhooks/endpoints/{id} \
  -H "Authorization: Bearer <supabase_jwt>"
```

## Requisitos da URL

* Deve usar **HTTPS** (HTTP não é aceito)
* Deve responder com status **2xx** em até **20 segundos**
* Deve estar acessível publicamente (sem firewall bloqueando)

> [!NOTE]
>
> Para desenvolvimento local, use ferramentas de tunnel como [ngrok](https://ngrok.com) ou [localtunnel](https://theboroer.github.io/localtunnel-www/) para expor sua aplicação local.

## Reentrega de Eventos

Se um webhook falhar na entrega, você pode solicitar reentrega manualmente:

```bash theme={null}
curl -X POST https://api.chargefy.io/api/v1/webhooks/events/{event_id}/redeliver \
  -H "Authorization: Bearer <supabase_jwt>"
```

## Monitoramento

### Listar Entregas

Acompanhe o status de entregas de webhooks:

```bash theme={null}
curl -X GET https://api.chargefy.io/api/v1/webhooks/deliveries \
  -H "Authorization: Bearer <supabase_jwt>"
```

Cada entrega inclui:

* `id` — Identificador da entrega
* `succeeded` — Se a entrega foi bem-sucedida
* `http_code` — Código HTTP retornado pelo seu servidor
* `response` — Corpo da resposta (para debug)
* `created_at` — Data/hora da tentativa

## Próximos Passos

> [card] [Eventos](https://scaleup-c34c4386.mintlify.site/integrate/webhooks/events.md)
>
> Lista completa de eventos disponíveis

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


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