Webhooks
Eventos Stripe processados automaticamente pelo QuickClaw.
Visao geral
O QuickClaw recebe webhooks do Stripe automaticamente para manter o estado dos bots, assinaturas e creditos sempre sincronizado. Voce nao precisa configurar nada — todo o processamento e feito internamente pela Edge Function stripe-webhook.
Cada evento aciona uma cadeia de acoes automaticas: ativacao de bots, renovacao de creditos, suspensao por disputas, entre outros.
Totalmente automatico
Todos os webhooks sao processados automaticamente. Voce nao precisa fazer nada — basta usar o QuickClaw normalmente e o sistema cuida do resto.
Eventos processados
Abaixo, cada evento Stripe e o que acontece quando ele e recebido:
| Evento | Acao automatica |
|---|---|
checkout.session.completed | Ativa bot, cria assinatura, envia email de boas-vindas |
invoice.paid | Renova creditos de assinatura do agente |
customer.subscription.updated | Atualiza tier e status do agente |
customer.subscription.deleted | Desativa bot (hard delete com backup via trigger) |
charge.refunded | Reverte creditos, ajusta saldo da conta |
charge.dispute.created | Pausa bot, marca como suspended |
charge.dispute.closed | Won: reativa bot | Lost: mantem suspensao, deleta bot |
checkout.session.completed
Disparado quando o usuario completa o checkout no Stripe. E o evento mais importante — ele inicia toda a cadeia de ativacao:
- Cria a assinatura no banco de dados vinculada ao agente
- Aloca um slot na VPS com menor carga (load balancing)
- Ativa o container do agente com todas as configuracoes
- Credita o saldo inicial de creditos baseado no tier
- Envia email de boas-vindas ao usuario
invoice.paid
Disparado mensalmente quando a fatura e paga com sucesso. Renova os creditos de assinatura do agente para o valor cheio do tier contratado. Creditos nao utilizados do ciclo anterior nao acumulam.
customer.subscription.updated
Disparado quando o usuario altera o plano (upgrade ou downgrade) ou quando o Stripe atualiza o status da assinatura (ex: past_due, unpaid). O QuickClaw sincroniza o tier e status do agente automaticamente.
customer.subscription.deleted
Disparado quando a assinatura e cancelada (pelo usuario ou por falta de pagamento). O agente e desativado via hard delete — o trigger SQL automaticamente faz backup dos dados do container (retido por 15 dias), libera o slot na VPS e limpa as chaves de API.
charge.refunded
Disparado quando um reembolso e emitido. O QuickClaw identifica se o pagamento era de assinatura ou topup e reverte os creditos correspondentes. Se o saldo resultante ficar negativo, o agente continua funcionando ate o proximo ciclo.
charge.dispute.created
Disparado quando o usuario abre uma disputa (chargeback) no banco ou operadora de cartao. O agente e imediatamente pausado e marcado como suspended ate que a disputa seja resolvida.
Suspensao imediata
Disputas resultam em suspensao automatica do agente para proteger a plataforma. O usuario e notificado por email sobre a situacao.
charge.dispute.closed
Disparado quando a disputa e resolvida pelo Stripe. Dois desfechos possiveis:
- Won (favoravel): A disputa foi resolvida a favor do QuickClaw. O agente e reativado automaticamente.
- Lost (desfavoravel): A disputa foi perdida. O agente permanece suspenso e e eventualmente deletado.
Seguranca de webhooks
O processamento de webhooks segue praticas rigorosas de seguranca:
- Assinatura verificada: Cada webhook e validado usando o webhook secret do Stripe. Requisicoes com assinatura invalida sao rejeitadas imediatamente.
- Idempotencia: Eventos duplicados sao ignorados automaticamente. O Stripe pode reenviar eventos em caso de falha, e o QuickClaw trata cada evento apenas uma vez.
- Eventos auditados: Todos os eventos processados sao registrados na tabela
stripe_eventscom timestamp, tipo e resultado do processamento.
Nada para configurar
A seguranca dos webhooks e gerenciada internamente. O webhook secret e armazenado como variavel de ambiente na Edge Function e nunca e exposto.
