Skip to main content
O webhook receiver é por onde o seu SaaS avisa o Retuno. Os callbacks são o caminho inverso: é por onde o Retuno avisa o seu SaaS quando o agente precisa executar uma ação durante uma conversa — aplicar desconto ou estender trial. Sem um callback configurado, o agente consegue conduzir o diálogo, diagnosticar a objeção e propor soluções, mas não consegue aplicar mudanças reais no seu produto. Com o callback, uma oferta aceita pelo cliente vira efeito no seu sistema na hora, na mesma conversa.

​
Onde configurar

A primeira configuração acontece no passo de Callbacks do onboarding. Depois, o gerenciamento fica em Configurações → Callbacks.

​
Como funciona

1

Você expõe um endpoint no seu SaaS

Um endpoint HTTPS que aceita POST com JSON. Ele vai receber as ações que o agente pedir para executar.
2

Registra a URL e um secret no Retuno

Em Callbacks, informe a URL do endpoint e, opcionalmente, um secret para assinar as requisições. Marque quais ações o Retuno pode executar no seu sistema.
3

Testa a conexão

O botão Testar conexão envia uma requisição de teste ao seu endpoint e valida a resposta. Se houve sucesso, a configuração fica marcada como Verificado.
4

O agente executa em tempo real

Quando o cliente aceita uma oferta numa conversa, o agente chama seu endpoint com a ação. Se a resposta é 2xx, o Retuno confirma ao cliente que a ação foi aplicada.

​
Ações suportadas

AçãoDescrição
apply_discountAplicar um desconto no plano do cliente.
extend_trialEstender o período gratuito do cliente.
Na tela de Callbacks você escolhe quais dessas ações estão habilitadas. Uma ação desabilitada nunca é chamada no seu endpoint, mesmo que o agente proponha.

​
Formato da requisição

  • Método: POST na URL do callback.
  • Content-Type: application/json.
  • Header X-Retuno-Signature (quando há secret): formato sha256=<hmac> — HMAC-SHA256 do corpo da requisição, calculado com o secret configurado.
  • Timeout: 5 segundos.
Corpo JSON: 
{
  "action": "apply_discount",
  "userId": "id-do-usuario-no-retuno",
  "value": 10,
  "conversationId": "id-da-conversa"
}
Campos:
  • action — apply_discount ou extend_trial.
  • userId — identificador do cliente final dentro do Retuno.
  • value — valor da oferta: percentual quando apply_discount, dias quando extend_trial.
  • conversationId — identificador da conversa em que a ação foi decidida. Útil para rastrear no seu lado.

​
Resposta esperada

  • 2xx — o Retuno considera que a ação foi aplicada com sucesso. O agente confirma ao cliente na conversa.
  • Qualquer outra resposta ou timeout após 5 segundos — o Retuno considera falha; o agente não confirma ao cliente e a conversa tende a escalar para humano, conforme os guardrails e o Modo Supervisão.

​
Assinatura e segurança

Quando você configura um secret, toda requisição inclui o header X-Retuno-Signature com o HMAC do corpo. No seu endpoint, recalcule o HMAC com o mesmo secret e compare — se não bater, rejeite. Isso garante que só o Retuno consegue disparar ações no seu sistema. Sem secret, a assinatura não é enviada. Nesse caso, proteja o endpoint por outros meios (IP allowlist, token em rota secreta, etc.).

​
Boas práticas

  • Torne o endpoint idempotente — o Retuno pode retentar em caso de timeout, e você não quer aplicar o mesmo desconto duas vezes. Use conversationId como chave de deduplicação.
  • Responda rápido — o agente está esperando para confirmar ao cliente na conversa. Mais de 5 segundos e a ação é considerada falha.
  • Valide a assinatura se usar secret. Nunca aceite cegamente.
  • Habilite apenas as ações que seu sistema sabe executar — se seu produto não tem trial, não habilite extend_trial.

​
Teste e verificação

Na tela de Callbacks, o botão Testar conexão envia um payload especial (action: "test") ao seu endpoint. O status do último teste aparece como Conectado, Timeout ou Falha, com a mensagem de erro quando houver. Use esse botão depois de cada alteração no seu endpoint para confirmar que a integração segue saudável.