Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.raposa.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Visão Geral

A integração com o Stripe permite que a Raposa receba automaticamente todos os eventos de pagamento, assinatura e cobrança do seu negócio. A Raposa extrai dados de produtos, clientes e receita para alimentar os dashboards de atribuição e ROI.
A Raposa suporta múltiplos tipos de evento do Stripe: checkouts, payment intents, invoices e charges — cobrindo desde vendas únicas até assinaturas recorrentes.

​
Pré-requisitos

​
Passo 1 — Gerar a URL do Webhook na Raposa

  1. Acesse a Raposa e vá até Configurações → Integrações ou crie/edite uma Operação
  2. Na seção de Webhooks, clique no card do Stripe
  3. A Raposa irá gerar automaticamente uma URL única:
https://app.raposa.com/api/webhook/stripe/{seu-id-unico}
  1. Copie essa URL

​
Passo 2 — Criar o Webhook no Stripe

  1. Acesse o Dashboard do Stripe → Developers → Webhooks
  2. Clique em ”+ Add endpoint”
  3. Configure:
    • Endpoint URL: Cole a URL copiada da Raposa
    • Eventos: Clique em “Select events” e adicione:
      • checkout.session.completed
      • payment_intent.succeeded
      • invoice.paid
      • charge.succeeded
  4. Clique em “Add endpoint”
Se você vende via Stripe Checkout, o evento checkout.session.completed é o mais importante. Para assinaturas recorrentes, adicione também invoice.paid.

​
Passo 3 — Copiar o Signing Secret

Após criar o endpoint:
  1. No Stripe, clique no endpoint que acabou de criar
  2. Na seção “Signing secret”, clique em “Reveal”
  3. Copie o valor (começa com whsec_...)
  4. Na Raposa, cole no campo “Webhook Signing Secret”
  5. Salve a configuração
O Signing Secret é essencial para a segurança. A Raposa usa ele para verificar que cada evento realmente veio do Stripe. Sem ele, os webhooks serão rejeitados.

​
Passo 4 — Testar a Conexão

  1. No Stripe, vá até o endpoint criado
  2. Clique em “Send test webhook”
  3. Selecione o evento checkout.session.completed e clique em “Send test webhook”
  4. Na Raposa, verifique se o status do webhook mudou para Ativo
Para um teste completo com dados reais, habilite o Modo de teste no Stripe e faça uma compra usando o cartão de teste 4242 4242 4242 4242.

​
Eventos Suportados

Evento StripeCaso de UsoO que a Raposa extrai
checkout.session.completedVenda via CheckoutProdutos dos line_items, cliente, valor total
payment_intent.succeededPagamento diretoProduto via metadata (product_id, product_name)
invoice.paidAssinatura recorrenteProdutos de cada line da invoice
charge.succeededCobrança avulsaProduto via metadata, dados do cliente

​
Como Enviar Dados de Produto via Metadata

Para os eventos payment_intent.succeeded e charge.succeeded, a Raposa lê os dados do produto a partir do campo metadata. Ao criar o Payment Intent no seu código, inclua: 
const paymentIntent = await stripe.paymentIntents.create({
  amount: 9990,
  currency: 'brl',
  metadata: {
    product_id: 'prod_001',
    product_name: 'Curso de Marketing Digital',
  }
});
Para checkout.session.completed, os produtos são extraídos automaticamente dos line_items — não é necessário configurar metadata.

​
Dados Capturados

A cada evento, a Raposa extrai:
  • Produto: Nome, ID, quantidade, valor
  • Cliente: ID do customer, email, nome (quando disponível)
  • Valor: Receita da transação
  • Tipo: Venda única, assinatura, cobrança avulsa
  • Status: Pago, falhado (apenas sucessos são processados como venda)
  • Data/hora: Timestamp do evento

​
Validação de Segurança

A Raposa utiliza a validação oficial do Stripe SDK:
  1. O Stripe envia o header Stripe-Signature com cada request
  2. A Raposa usa stripe.webhooks.constructEvent() com o Signing Secret para validar
  3. Se a assinatura for inválida ou o evento for manipulado, o webhook é rejeitado (status 400)
Essa é a validação recomendada pelo próprio Stripe e protege contra falsificação de eventos.

​
Modo Teste vs. Produção

O Stripe possui ambientes separados de teste e produção:
AmbienteSigning SecretDados
Testewhsec_... (do modo teste)Transações simuladas
Produçãowhsec_... (do modo live)Transações reais
Certifique-se de usar o Signing Secret do ambiente correto. O secret do modo teste não funciona com eventos de produção e vice-versa.

​
Solução de Problemas

O Signing Secret está incorreto ou é do ambiente errado (teste vs. produção).
  1. No Stripe, acesse o endpoint e clique em “Reveal” no Signing Secret
  2. Na Raposa, atualize o campo com o valor correto
  3. Certifique-se de que está usando o secret do mesmo ambiente (teste ou live)
  1. Para checkout.session.completed: verifique se o checkout tem produtos nos line_items
  2. Para payment_intent.succeeded: verifique se está enviando product_id e product_name no metadata
  3. Verifique se a operação correta está selecionada na Raposa
  1. No Stripe, vá até o endpoint → aba “Attempts” para ver o erro detalhado
  2. Se o erro for 401 ou 400, revise o Signing Secret
  3. O Stripe tenta reenviar eventos com falha por até 72h com backoff exponencial
O Stripe pode reenviar eventos em caso de timeout. A Raposa possui proteção contra duplicação via event.id, mas se estiver vendo duplicatas, verifique se não criou endpoints duplicados no Stripe.
Certifique-se de que o pagamento está vinculado a um Customer no Stripe. Para Payment Intents criados sem customer, a Raposa não consegue extrair email/nome.