Sumário
- Quais eventos do Stripe realmente precisam de você
- Passo 1 — Um canal por nível de urgência
- Passo 2 — Adicione os endpoints no Stripe
- Passo 3 — Transforme o payload em algo legível
- Passo 4 — Teste sem esperar um pagamento real
- O que essa montagem não entrega
- Perguntas frequentes
- O Stripe consegue me ligar direto?
- Um alerta de contestação vai mesmo me acordar?
- Meu sócio pode receber os mesmos alertas?
- E o modo de teste?
- Fechando
- Conteúdo relacionado
O Stripe manda e-mail sobre tudo e sobre nada. Uma cobrança bem-sucedida, uma renovação de assinatura que falhou e um chargeback chegam como o mesmo tipo de mensagem na mesma caixa de entrada, e quando você lê já perdeu a diferença entre elas.
A solução não é mais notificação. É dar a cada evento do Stripe a urgência que ele realmente merece: um push discreto quando alguém paga, um alerta sensível ao tempo quando uma renovação falha, e uma ligação quando aparece uma contestação com prazo de resposta.
Quais eventos do Stripe realmente precisam de você
Nem todo evento merece uma notificação, e os que merecem não são igualmente urgentes.
| Evento do Stripe | Por que importa | Urgência |
|---|---|---|
payment_intent.succeeded | Alguém pagou. Bom saber, nunca urgente. | Normal |
invoice.payment_failed | Uma renovação falhou. Existe uma janela de novas tentativas antes de a assinatura cair. | Sensível ao tempo |
charge.dispute.created | Um chargeback. O Stripe informa um prazo de resposta definido pela bandeira, e perder o prazo perde o caso automaticamente. | Chamada |
payment_intent.payment_failed | Um pagamento avulso falhou. Útil em volume, barulhento um a um. | Normal, ou nenhuma |
A contestação é a única que justifica uma ligação. O resto pode esperar você pegar o telefone; uma contestação notada uma semana depois é dinheiro que você não ia manter mesmo.
Passo 1 — Um canal por nível de urgência
Crie três canais no Echobell, porque urgência é um ajuste por canal:
- Stripe · Receita — notificações normais, para pagamentos bem-sucedidos
- Stripe · Pagamento falhou — sensível ao tempo
- Stripe · Contestação — chamada
Copie a URL de webhook de cada canal nas configurações dele. Você vai apontar o Stripe para as três.
Já aproveite e ative Somente POST em cada uma. O Stripe sempre envia via POST, e isso evita que uma prévia de link ou o autocompletar da barra de endereços dispare seu canal sem querer.
Passo 2 — Adicione os endpoints no Stripe
No painel do Stripe, vá em Developers → Webhooks → Add endpoint, cole a URL do canal e selecione apenas os eventos que aquele canal deve tratar.
Adicione um endpoint por canal em vez de um endpoint para tudo. O Stripe deixa escolher eventos por endpoint, então o roteamento acontece do lado dele e seus canais ficam simples.
Se preferir um único endpoint, aponte-o para um canal e filtre com uma condição:
type == "charge.dispute.created"
Condições são escritas sem as chaves {{ }} que os templates usam.
Passo 3 — Transforme o payload em algo legível
O Stripe envia um corpo JSON com este formato:
{
"type": "charge.dispute.created",
"data": {
"object": {
"amount": 4900,
"currency": "usd",
"reason": "fraudulent",
"status": "warning_needs_response"
}
}
}Então os templates do canal entram em data.object:
Título
Contestação: {{data.object.reason}}
Corpo
{{data.object.amount}} {{data.object.currency}} contestados
Status: {{data.object.status}}
Uma pegadinha que pega todo mundo: os valores do Stripe estão na menor unidade da moeda. 4900 é US$ 49,00, não US$ 4.900. Os templates do Echobell substituem o valor como está, então ou você divide antes de enviar, ou escreve a moeda depois e lê como centavos. Se o número precisa estar certo de primeira, coloque a divisão no que estiver entre o Stripe e o Echobell — um Worker, uma automação, seu próprio endpoint.
Para o canal de receita, a mesma ideia com menos palavras:
Título
+{{data.object.amount}} {{data.object.currency}}
Corpo
{{data.object.description}}
Passo 4 — Teste sem esperar um pagamento real
A CLI do Stripe consegue disparar payloads reais no seu endpoint:
stripe trigger payment_intent.succeeded
stripe trigger charge.dispute.createdFaça isso antes de depender disso. É também o jeito mais rápido de ver o que o seu template renderiza quando um campo que você achava garantido chega como null.
O que essa montagem não entrega
Dois limites que vale conhecer antes de colocá-la na frente da sua receita.
O Echobell não verifica a assinatura do Stripe. O Stripe assina todo webhook com um cabeçalho Stripe-Signature, e verificar isso exige o segredo do endpoint. O endpoint de webhook do Echobell não faz essa checagem, então a URL do canal é a única coisa que o protege. Trate-a como segredo, mantenha Somente POST ligado e não cole em repositório público nem em captura de tela.
Dá para adicionar uma checagem fraca com uma condição:
header["stripe-signature"] != ""
Isso confirma que algo está enviando uma requisição no formato do Stripe. Não confirma que foi o Stripe. Se uma notificação forjada causasse dano real — e não só um momento de confusão — coloque seu próprio endpoint na frente, verifique a assinatura ali e faça ele chamar o Echobell.
Isso é um caminho de alerta, não um livro-caixa. O Stripe repete entregas de webhook que falharam, mas notificações não são registro do que aconteceu. Concilie contra o Stripe, não contra seu histórico de notificações.
Perguntas frequentes
O Stripe consegue me ligar direto?
Não. O Stripe manda e-mail e webhooks. Uma ligação significa encaminhar um webhook para algo capaz de fazê-la.
Um alerta de contestação vai mesmo me acordar?
Se o canal estiver em modo chamada, sim — ele chega como ligação recebida e toca atravessando o Foco e o Não perturbe. Veja como atravessar o modo Foco do iOS para alertas críticos.
Meu sócio pode receber os mesmos alertas?
Pode. Compartilhe o canal e cada assinante escolhe o próprio tipo de notificação. Você fica com as ligações enquanto outra pessoa recebe um push discreto pelo mesmo evento.
E o modo de teste?
Eventos em modo de teste do Stripe vão para endpoints registrados em modo de teste. Registre a URL do canal nos dois se quiser ver esse tráfego, ou só em teste até confiar na montagem.
Fechando
Três canais, três endpoints, um template em cada. A questão não é você ser notificado pelo Stripe — você já era. É um chargeback parar de parecer exatamente um recibo.
Baixe o Echobell para iPhone ou pegue no Google Play, depois rode stripe trigger charge.dispute.created e deixe seu telefone tocar uma vez de propósito.