Skip to main content
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: chargefy_whs_... (guarde em local seguro!)

​
Resposta

{
  "id": "wep_abc123",
  "url": "https://seusite.com.br/webhooks/chargefy",
  "format": "raw",
  "secret": "chargefy_whs_...",
  "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

FormatoDescriçãoUso
rawPayload JSON padrãoIntegrações customizadas
discordFormato Discord webhookNotificações em canais Discord
slackFormato Slack webhookNotificaçõ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