Webhooks, regras, APIs externas e JSON do fluxo

Webhooks externos

Cadastrar endpoint para receber eventos

Webhooks externos permitem que sistemas terceiros recebam eventos operacionais do RitmaChat. Use endpoints HTTPS estáveis e com autenticação do lado receptor.

Acesse Webhooks externos.
Crie um endpoint com nome e URL HTTPS. O identificador interno é criado automaticamente.
Defina eventos que devem ser entregues ao endpoint.
Configure segredo ou assinatura quando a integração exigir validação de origem.
Salve e execute um evento de teste antes de ativar regra em produção.
Acompanhe entregas em Entregas de webhook.

Print reservado Cadastro de webhook externo Imagem real sugerida: formulário de endpoint sem exibir segredo.

Mascarar URL privada, tokens e headers sensíveis no print final.

Regras

Automatizar ações por evento

Regras conectam eventos, filtros e ações. Use prioridade e filtros estritos para evitar automação agindo em conversas erradas.

Criar uma regra

Acesse Regras.
Crie uma nova regra com nome e descrição.
Escolha o evento gatilho.
Configure filtros de instância, departamento, status ou dados do cliente.
Defina a ação: transferir, etiquetar, acionar webhook, iniciar chatbot ou outra ação disponível.
Salve como inativa, teste com evento controlado e ative depois da validação.

Cuidados

Evite regra sem filtro em workspace com múltiplos canais.
Documente prioridade quando duas regras podem reagir ao mesmo evento.
Revise execuções em Execuções de regras.
Desative regras antigas antes de substituir por nova versão.

Eventos

Quando enviar dados para sistemas externos

Use webhooks para integrações que precisam reagir a mudanças operacionais. Use filtros para evitar volume desnecessário e payloads grandes.

Evento	Uso típico	Dados importantes
Nova conversa	Abrir lead, ticket ou registro em CRM externo.	Workspace, instância, cliente, protocolo, origem e departamento.
Mensagem recebida	Alimentar BI, auditoria ou classificador externo.	Direção, texto, mídia, remetente, horário e conversa.
Status alterado	Atualizar kanban, SLA ou painel de operação.	Status anterior, novo status, responsável e motivo.
Transferência	Sincronizar dono, fila ou unidade de atendimento.	Origem, destino, nota, usuário e snapshot quando existir.
Campanha atualizada	Consolidar resultado de comunicação ativa.	Campanha, destinatário, status, erro e mensagem vinculada.
Chatbot executado	Monitorar automação e pontos de queda.	Fluxo, versão, nó atual, status, variável e erro.

Nós técnicos

API externa e webhook dentro do chatbot

Use nós técnicos quando o chatbot precisa consultar sistemas externos, gravar dados ou disparar integrações durante o atendimento.

Nó	Quando usar	Configuração mínima	Saídas esperadas
`api`	Consultar endpoint arbitrário por HTTP.	`url`, `method`, `payload_template`.	`success`, `error`, `timeout`.
`webhook`	Acionar endpoint cadastrado em Webhooks externos.	`endpoint_slug` e payload opcional.	`success`, `error`, `timeout`.
`ai`	Interpretar texto, gerar resposta ou classificar intenção.	`prompt` e, idealmente, `response_variable`.	`success`, `fallback`, `error`.

Payloads

Contrato mínimo de integração

Padronize payloads para que o sistema receptor consiga rejeitar, registrar e reprocessar eventos com segurança.

{
  "event": "conversation.status_changed",
  "workspace": {
    "slug": "empresa-exemplo"
  },
  "conversation": {
    "protocol_number": "2026-000123",
    "status": "waiting_customer",
    "department": "suporte",
    "assignee": "ana"
  },
  "customer": {
    "name": "Cliente Exemplo",
    "phone": "5511999999999"
  },
  "occurred_at": "2026-05-22T12:00:00Z"
}

Dados sensíveis

Envie apenas o necessário para a finalidade da integração. Não inclua tokens, segredos, URLs privadas ou anexos completos quando um identificador já resolve o caso.

JSON avançado

Estrutura completa de fluxo

O editor visual gera essa estrutura, mas o JSON é útil para revisão técnica e diagnóstico de publicação.

{
  "settings": {
    "timeout_minutes": 60,
    "max_attempts": 3
  },
  "start": "saudacao",
  "nodes": [
    {
      "id": "saudacao",
      "type": "message",
      "title": "Saudação",
      "config": {
        "text": "Olá, {{ customer.name }}. Seu protocolo é {{ protocol_number }}."
      }
    },
    {
      "id": "menu",
      "type": "menu",
      "title": "Menu",
      "config": {
        "text": "Escolha: 1 financeiro, 2 suporte.",
        "options": [
          {"id": "financeiro", "label": "Financeiro", "match": ["1", "financeiro", "boleto"]},
          {"id": "suporte", "label": "Suporte", "match": ["2", "suporte", "ajuda"]}
        ]
      }
    },
    {
      "id": "financeiro",
      "type": "department",
      "title": "Transferir financeiro",
      "config": {
        "department_slug": "financeiro",
        "note": "Cliente pediu atendimento financeiro."
      }
    },
    {
      "id": "suporte",
      "type": "human",
      "title": "Chamar humano",
      "config": {
        "note": "Cliente pediu suporte técnico."
      }
    }
  ],
  "edges": [
    {"source": "saudacao", "source_port": "default", "target": "menu"},
    {"source": "menu", "source_port": "option_financeiro", "target": "financeiro"},
    {"source": "menu", "source_port": "option_suporte", "target": "suporte"}
  ]
}

Segurança de integração

Regras mínimas para endpoints

Trate integrações como superfície crítica de produção.

Use somente HTTPS público e estável para endpoints externos.
Não coloque usuário, senha, token ou segredo dentro da URL.
Configure timeout curto; o runtime limita chamadas externas para evitar fila presa.
Salve respostas externas em variável apenas quando forem úteis para o fluxo.
Tenha rota de erro conectada para todo nó api ou webhook.
Revise entregas e logs antes de aumentar volume.