Em detalhe
Cobrança por usuário com Stripe e webhooks que resistem a reenvios
Publicado em · 7 min de leitura· Anton Shubin
Também disponível em: العربية, Deutsch, English, Español, Français, 日本語, Русский e 简体中文

Em resumo
- No Seed, a quantidade da assinatura no Stripe é o número de membros do grupo, dono incluído. O Stripe faz o rateio; o app não calcula dinheiro.
- O membro entra primeiro e a cobrança vem depois: uma tarefa do worker informa a nova quantidade ao Stripe e repete com a mesma chave de idempotência enquanto o Stripe estiver fora.
- O id de cada evento é salvo na mesma transação que o aplica: um reenvio não muda nada, e uma falha desfaz as duas coisas para o Stripe tentar de novo.
- Um evento antigo nunca volta um plano para trás, e uma tarefa noturna corrige qualquer número de assentos que tenha divergido.
Como cobrar um SaaS por usuário com Stripe sem que a fatura se afaste da equipe real? No Seed, a quantidade da assinatura é simplesmente o número de membros do grupo, e o app não confia em uma única chamada nem em um único webhook para mantê-la assim. A mudança de membros é salva primeiro; uma tarefa que se repete informa a nova quantidade ao Stripe; cada webhook é gravado pelo id do evento na mesma transação que o aplica; e uma tarefa noturna corrige o que escapou.
Este texto é para quem está colocando cobrança por equipe em um SaaS, e para quem já viu um handler de webhook funcionar bem até o Stripe reenviar um evento. Está tudo no código do Seed, sob licença MIT, e cito as linhas reais.
O que significa cobrança por usuário no Seed?
A cobrança pertence a um grupo, a equipe no Seed. Cada grupo tem uma assinatura, paga pelo dono. O
catálogo tem dois planos (PLANS):
| Plano | Preço | Membros | Teste |
|---|---|---|---|
| Free | 0 | até 3 | não |
| Pro | € 9,00 por membro ao mês | até 50 | 14 dias |
"Por membro" quer dizer que a quantidade da assinatura no Stripe é o número de membros do grupo, contando o dono. É o mesmo número que o limite de 50 usa, então o assento tem uma definição só, e não duas que discordam. Um convite pendente não reserva assento; aceitá-lo, sim.
Veja quanto uma equipe paga com os preços da demo. Mexa no controle:
Interativo
Quanto o plano Pro da demo custa para sua equipe
O Pro é cobrado por membro. Defina o tamanho da sua equipe.
- Sua equipe, por mês
- € 45,00
- Por membro, por mês
- € 9,00
Cinco pessoas no Pro pagam € 45 por mês. O dono vê o preço de mais um assento antes de convidar
alguém: o formulário de convite mostra quanto o novo membro acrescenta e pede que ele aceite. A API
recusa um convite sem esse aceite (SEAT_PRICE_NOT_ACCEPTED), então a regra vale mesmo quando o
formulário é enviado sem JavaScript.
Por que o membro entra antes de o Stripe saber?
Porque um Stripe lento nunca deve impedir alguém de entrar em uma equipe. O código óbvio chama o Stripe dentro da requisição "aceitar convite": se o Stripe demorar demais, ou a pessoa não entra, ou entra e a cobrança fica errada para sempre. As duas coisas são ruins, e a segunda passa despercebida.
O Seed salva primeiro a mudança de membros, em uma transação própria. O commit grava uma linha no
outbox, e o worker transforma cada mudança (entrou, foi removido, saiu) em uma tarefa de
sincronização de assentos. A tarefa lê a quantidade na hora em que roda e só chama o Stripe se ela
for diferente da salva (seat-sync.ts):
const members = await new PostgresInvitationRepository(sql).countMembers(groupId)
if (members < 1 || row.quantity === members) return
const result = await provider.updateQuantity({
subscriptionId: row.providerSubscriptionId,
quantity: members,
// A retry of this row asks for the same count with the same key; a later count gets its own.
idempotencyKey: `seats:${event.id}:${members}`,
})
if (!result.ok) {
throw new Error(`seat sync of group ${groupId} failed: ${result.error.code} ...`)
}
Três detalhes seguram tudo:
- A quantidade é lida quando a tarefa roda, não quando entrou na fila. Cinco pessoas entrando em um minuto precisam de uma chamada certa, não de cinco disputando.
- A chave de idempotência nomeia a tarefa e a quantidade. Se o Stripe aplicou a mudança e a resposta se perdeu, a nova tentativa manda a mesma chave, e o Stripe devolve o primeiro resultado em vez de aplicar duas vezes.
- Uma falha lança erro. O sistema de tarefas tenta de novo depois de 1 s, 2 s, 4 s e assim por diante, com até 15 minutos de intervalo, 20 vezes, cerca de duas horas e meia (jobs.md).
A mudança de quantidade pede ao Stripe proration_behavior=create_prorations, o
padrão dele: o restante do período é
somado à próxima fatura ou abatido dela. O app nunca calcula sozinho um euro rateado. Conta de
dinheiro que eu não escrevo é conta que eu não erro.
E se a sincronização nunca chegar?
Mais dois caminhos pegam o caso, porque duas horas e meia de tentativas não são "para sempre":
- O webhook também confere. Quando o Stripe informa uma assinatura cuja quantidade não bate com o número de membros, a mesma transação que salva o evento coloca uma sincronização na fila. Assim se corrige um checkout aberto antes de alguém entrar.
- Uma tarefa noturna confere todo grupo pagante. Às 03:00, a limpeza procura cada assinatura por membro cuja quantidade salva difere da do grupo e coloca uma sincronização na fila. Isso cobre uma queda longa do Stripe e uma mudança sem evento do grupo, como um membro que apaga a própria conta.
Então os assentos ficam certos depois da próxima mudança, do próximo webhook ou da próxima noite, o que vier primeiro. Prefiro isso a um design que só acerta se todas as chamadas derem certo.
Como deixar um webhook do Stripe seguro para reenvios?
O Stripe reenvia uma entrega que falhou por até três dias no modo live, e avisa que um endpoint pode receber o mesmo evento mais de uma vez. Um handler que soma um assento ou manda um e-mail a cada entrega vai, cedo ou tarde, fazer isso duas vezes.
O webhook do Seed faz três coisas em ordem fixa. Primeiro, a assinatura: o adaptador
@spy4x/billing confere o cabeçalho Stripe-Signature contra o
corpo bruto, com janela de cinco minutos, antes de ler um byte de JSON. Assinatura inválida recebe
400. Depois, tudo acontece em uma transação do Postgres que começa gravando o id do evento
(postgres-billing-repository.ts):
return await this.sql.begin(async (transaction) => {
const stored = await transaction`
INSERT INTO billing_events (id, event_type) VALUES (${event.id}, ${event.type})
ON CONFLICT (id) DO NOTHING
RETURNING id
`
if (stored.length === 0) return "duplicate"
// ... apply the subscription, queue mails and seat syncs, record the plan change
})
billing_events.id é a chave primária, então a segunda entrega não insere nada e retorna sem tocar
na assinatura. Como o id é gravado dentro da transação, o caso oposto também é seguro: se algo
falhar depois, o id é desfeito junto com o resto, a rota responde 500 e o reenvio do Stripe tem
uma segunda tentativa limpa. Gravar o id primeiro e aplicar depois, em dois passos, perderia o
evento na primeira vez que um deploy reiniciasse a API entre os dois.
Os e-mails ao dono (pagamento recusado, fim do teste, fim do plano) entram no outbox nessa mesma
transação, então um evento repetido nunca coloca um segundo e-mail na fila. Um evento que o Seed não
trata recebe 200, e o Stripe para de enviá-lo.
E os eventos que chegam fora de ordem?
O Stripe não garante a ordem dos eventos. Um
customer.subscription.updated atrasado dizendo "trialing" não pode desfazer o active que veio
antes. O Seed grava a assinatura com um upsert que só anda para a frente:
ON CONFLICT (group_id) DO UPDATE SET ...
WHERE (subscriptions.provider_event_at, subscriptions.provider_event_rank)
<= (EXCLUDED.provider_event_at, EXCLUDED.provider_event_rank)
Primeiro vale a hora do evento, e o tipo desempata: criado, depois atualizado, depois excluído. Um
evento mais antigo não casa com nenhuma linha e não muda nada. Uma segunda regra no mesmo WHERE
impede que uma assinatura nova que não paga (uma cobrança recusada atrasada, por exemplo) tome o
lugar de uma que paga.
Vou ser direto sobre o limite. A documentação do Stripe diz para não usar created para ordenar
eventos, porque ele vem em segundos inteiros. O Seed usa esse campo só como trava contra
retrocesso, nunca para achar duplicatas, que é para isso que existe o id do evento. Dois eventos do
mesmo tipo no mesmo segundo, chegando invertidos, ainda deixam o mais antigo salvo, até o próximo
evento ou uma mudança no portal corrigir. Esse caso está descrito na
documentação de cobrança, e a correção espera
spy4x/ts-libs#380. Prefiro contar a deixar você
descobrir.
Os testes provam isso?
Eles rodam contra um Postgres de verdade. Os 26 passos da suíte do webhook
(tests/integration/billing.integration.test.ts) incluem "uma segunda entrega do mesmo evento não
muda nada" e "um evento mais antigo que o salvo nunca volta o plano". Os assentos têm sua própria
suíte (tests/integration/seat-billing.integration.test.ts), com passos como "um membro removido e
um que sai diminuem um cada" e "a tarefa noturna coloca na fila uma mudança de assentos para cada
grupo divergente".
O que o Seed não faz?
Para você saber antes de construir em cima dele:
- Um plano pago, mensal, por membro. Sem cobrança por uso ou medição, sem faixas. Adicionar um plano são cinco passos em Plans and limits.
- Só Stripe. O código conversa com uma interface de provedor, mas o Stripe é o único adaptador que existe. Dá para desligar a cobrança também, e aí todo grupo tem todos os recursos.
invoice.paideinvoice.payment_failedsão salvos, mas ainda não mudam nada. O plano segue o status da própria assinatura.- O dinheiro fica no Stripe. O app guarda o que os webhooks informam e nunca decide um plano por conta própria.
Experimente
Abra a demo, crie um grupo e veja a aba Cobrança; convide alguém e você verá o preço do assento antes de enviar. A versão curta está na página de cobrança, Set up billing leva você do zero ao Stripe real, primeiro no modo de teste, e os grupos têm sua própria página. Se o seu handler de webhook grava o id do evento em um passo e aplica em outro, essa é a primeira linha que eu mudaria hoje.


