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

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"
  }'

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

{
  "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"
}

O secret só é exibido na criação. Armazene-o em local seguro — você precisará dele para verificar assinaturas.

​

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

curl -X GET https://api.chargefy.io/api/v1/webhooks/endpoints \
  -H "Authorization: Bearer <supabase_jwt>"

​

Atualizar Endpoint

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:

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

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

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)

Para desenvolvimento local, use ferramentas de tunnel como ngrok ou localtunnel para expor sua aplicação local.

​

Reentrega de Eventos

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

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:

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

Eventos

Lista completa de eventos disponíveis

Delivery & Verificação

Retry, verificação HMAC e troubleshooting