O Retuno não observa o seu produto por fora. Quem dispara o agente é você, enviando eventos HTTP para o endpoint do webhook receiver. Sem isso, o agente não entra em ação.
Se você usa Stripe para cobrar clientes, conecte sua conta Stripe e o Retuno detecta cancelamentos, falhas de pagamento e disputas automaticamente — sem instrumentar o webhook receiver para esses eventos. As duas integrações coexistem: a Stripe cobre os sinais de billing e o webhook receiver complementa com sinais que só o seu produto enxerga (inatividade, queda de uso, eventos de tracking). Onde pegar o endpoint e o token
Acesse Configurações → Webhook no painel. A página exibe:
- A URL base do endpoint (mesma para todos os eventos).
- O token de autenticação da sua organização.
- Um botão para rotacionar o token quando você precisar revogar e gerar um novo.
O token dá acesso de escrita a todos os eventos da sua conta. Guarde em um local seguro no seu sistema e nunca exponha no frontend ou em logs.
Eventos suportados
O webhook receiver aceita dois tipos de evento com comportamentos diferentes: eventos de gatilho disparam uma conversa do agente; eventos de tracking alimentam a detecção preditiva.
Eventos de gatilho
Disparam o agente e exigem customer.phone no padrão E.164 (ex.: +5511999999999). No painel, em Guardrails → Eventos gatilho, você marca quais destes eventos ativam o agente no seu produto.
| Evento | Quando enviar |
|---|
subscription.cancelled | Cliente cancelou a assinatura. |
user.inactive | Cliente parou de usar o produto por um período significativo. |
usage.dropped | O consumo do cliente caiu abaixo do padrão. |
payment.failed | Falha de pagamento ainda sem cancelamento confirmado. |
trial.expired | Período de trial terminou sem conversão. |
plan.downgraded | Cliente reduziu o plano contratado. |
subscription.paused | Cliente pausou a assinatura em vez de cancelar. |
cancel_page.visited | Cliente acessou a página de cancelamento no seu produto (sinal preditivo). |
export_data.requested | Cliente solicitou exportar os próprios dados (sinal preditivo). |
Eventos de tracking
customer.phone é opcional. Não disparam conversa imediata, mas são armazenados e usados pela plataforma para mapear o comportamento de cada cliente. Com esses eventos, o Retuno identifica padrões — por exemplo, a frequência de user.login esperada de cada usuário — e detecta desvios que antecipam risco de churn, acionando um gatilho preditivo antes que o cliente tome uma decisão de saída. Quanto mais completa for a sua instrumentação, mais cedo o Retuno consegue agir.
| Evento | Quando enviar |
|---|
user.created | Novo usuário criou conta no seu produto. |
user.login | Login de usuário. Alimenta detecção de queda de frequência. |
onboarding.completed | Usuário concluiu o onboarding do seu produto. |
feature.used | Usuário usou uma feature relevante. |
aha_moment.reached | Usuário atingiu o momento “aha” definido pelo seu time. |
usage.threshold_crossed | Uso cruzou um limiar pré-definido (para cima ou para baixo). |
support.ticket_opened | Usuário abriu ticket de suporte. |
support.ticket_resolved | Ticket de suporte foi resolvido. |
error.encountered | Usuário encontrou um erro relevante no seu produto. |
feature.searched_not_found | Usuário procurou uma feature que não existe no seu produto. |
trial.started | Trial iniciado. |
trial.ending_soon | Trial está próximo de expirar. |
plan.upgraded | Usuário fez upgrade de plano. |
payment.retried | Nova tentativa de cobrança após falha. |
payment.recovered | Pagamento recuperado após falha. |
invoice.generated | Fatura gerada. |
invoice.paid | Fatura paga. |
user.invited_teammate | Usuário convidou um colega. |
nps.submitted | Usuário respondeu NPS. |
csat.submitted | Usuário respondeu CSAT. |
feedback.submitted | Usuário deixou feedback aberto. |
billing_page.visited | Usuário visitou a página de cobrança no seu produto. |
Como enviar
De forma resumida:
- Método:
POST na URL do webhook receiver.
Content-Type: application/json.- Header de autenticação:
Authorization com o token exibido no painel.
- Corpo JSON com os campos
event, customer e metadata — o schema exato está em Formato de evento.
Para o contrato completo (schema do payload, campos obrigatórios, formato de erro, códigos HTTP) veja Webhook receiver e Envelope e formato de evento.
Boas práticas
- Envie em tempo quase real, não em batch — o agente perde efetividade se o evento chega horas depois.
- Envie os eventos de tracking que conseguir — quanto mais completos, mais cedo o Retuno consegue agir preditivamente.
- Envie o telefone do cliente sempre que possível, mesmo em eventos de tracking onde ele é opcional — é o canal pelo qual o agente vai falar com o cliente se um gatilho for disparado.
- Guarde o token em local seguro — ele dá acesso de escrita à sua conta do Retuno.
