Skip to main content
Diferente do webhook receiver — onde você envia ao Retuno — nos callbacks o Retuno envia ao seu SaaS quando o agente precisa executar uma ação durante a conversa. Para o contexto de uso e configuração no painel, veja o guia Callbacks.

​
Endpoint

Você expõe uma URL HTTPS no seu SaaS. A URL é registrada em Configurações → Callbacks no painel junto com um secret opcional e a lista de ações habilitadas.
  • Método: POST.
  • Content-Type: application/json.
  • Timeout: 5 segundos. Se o Retuno não receber resposta nesse prazo, considera a ação falha.

​
Autenticação (HMAC)

Quando você configura um secret no painel, toda requisição inclui o header: 
X-Retuno-Signature: sha256=<hmac>
Onde <hmac> é o HMAC-SHA256 do corpo cru da requisição, calculado com o secret. Sem secret configurado, o header não é enviado. Nesse caso, proteja o endpoint por outros meios (IP allowlist, rota com token em URL, etc.). Exemplo de verificação em Node.js: 
import crypto from "node:crypto";

function verifyRetunoSignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}
Use comparação em tempo constante (timingSafeEqual) para evitar ataques de timing.

​
Ações suportadas

AçãoDescrição
apply_discountAplicar um desconto no plano do cliente.
extend_trialEstender o período gratuito do cliente.
Ações habilitadas por conta são controladas no painel. Uma ação desabilitada nunca é enviada ao seu endpoint, mesmo que o agente proponha na conversa.

​
Payload de ação real

{
  "action": "apply_discount",
  "userId": "usr_42",
  "value": 10,
  "conversationId": "cnv_01HK9T7F2E6QZ0ABCD1234"
}
CampoTipoDescrição
actionstring"apply_discount" ou "extend_trial".
userIdstringIdentificador do cliente final dentro do Retuno.
valuenumberPercentual quando apply_discount (ex.: 10 = 10%); dias quando extend_trial (ex.: 7 = 7 dias).
conversationIdstringIdentificador da conversa em que a ação foi decidida. Útil para idempotência no seu lado.

​
Payload de teste

O botão Testar conexão no painel dispara um payload especial: 
{
  "action": "test",
  "timestamp": "2026-04-23T14:30:00.000Z",
  "organizationId": "org_9001"
}
Seu endpoint deve tratar esse payload sem efeito colateral — não aplicar desconto, não estender trial — e retornar 2xx. O Retuno usa a resposta para marcar o callback como Verificado no painel.

​
Resposta esperada

  • 2xx — o Retuno considera a ação aplicada com sucesso; o agente confirma ao cliente na conversa.
  • Qualquer outra resposta (incluindo 4xx e 5xx) ou timeout após 5s — o Retuno considera falha; o agente não confirma ao cliente e a conversa tende a escalar para humano conforme Modo Supervisão e Guardrails.

​
Recomendações de segurança

  • Valide a assinatura HMAC sempre que o secret estiver configurado.
  • Torne o endpoint idempotente usando conversationId como chave de deduplicação — evite aplicar o mesmo desconto duas vezes caso haja reentrega.
  • Responda rapidamente — o timeout é curto; use fila assíncrona se a ação depender de processamento demorado.
  • Habilite apenas as ações que seu sistema sabe executar — não habilite extend_trial se seu produto não tem trial.