Restringir uma instalação on-premise por IP
Esta página é para operadores de uma instalação on-premise do MonoChat. Ela explica como limitar o aplicativo web às suas próprias redes no nível de rede (nginx ou firewall), sem bloquear os serviços que precisam chamar o MonoChat pela internet.
O MonoChat não tem uma lista de IPs permitidos própria. A restrição fica no seu nginx, balanceador de carga ou firewall e vale para toda a instalação, não para um único tenant.
O que restringir e o que manter aberto
| Manter restrito às suas redes | Manter acessível pela internet |
|---|---|
| O aplicativo web e tudo o que não estiver listado à direita | Os caminhos de webhook e callback das tabelas abaixo |
O endpoint DDP/WebSocket ao qual o aplicativo web se conecta (/websocket) |
Restrinja a interface web e o endpoint WebSocket juntos: o aplicativo usa os dois. Para todos os demais, permita apenas os caminhos abaixo e bloqueie o resto.
Caminhos que os serviços externos chamam
Cada caminho abaixo é registrado pelo servidor do MonoChat. Um caminho construído a partir de uma configuração é o hookPath que você definiu no servidor (em channelConnectors.<name> ou paymentSystemConnectors.<name> nas configurações do servidor); o sufixo é adicionado pelo código. Abra apenas os conectores que você usa.
Canais
| Caminho | Chamado por | Definido em |
|---|---|---|
<hookPath>/webhooks (POST) | omni-message, para WhatsApp Cloud, WhatsApp Gupshup, Instagram, Messenger, Telegram, TikTok, Twilio SMS e Varan OTP | packages/app-connectors-om2-*/src/webhooks/webhook.ts; hookPath de channelConnectors.whatsappBusinessVegaCloud, whatsappBusinessVegaGupshup, instagramCastor, messengerRigel, telegramBotRegulus, tikTokTimir, twilioSms, varanOtp |
<hookPath>/webhooks, <hookPath>/sessions, <hookPath>/messages (POST) | Seus próprios sistemas, pelo canal Messages API | channelConnectors.messagesApi.hookPath, packages/app-connectors-messages-api/src/webhooks/webhook.ts |
<hookPath>/message, <hookPath>/info (POST) | Chatwoot | channelConnectors.chatwoot.hookPath, packages/app-connectors-chatwoot/src/webhook.ts |
<hookPath>/inbound (POST) | O provedor de SIP (canais generic SIP e Sonitel SIP) | channelConnectors.genericSip.hookPath, channelConnectors.sonitelSip.hookPath |
/api/facebook/channels/:channelId/flows/:flowId (POST) | WhatsApp, para WhatsApp Flows | server/api/whatsapp-flow.js |
Os provedores de canal (Meta, Telegram, TikTok, Twilio) não chamam o MonoChat diretamente. Eles chamam o webhook listener do omni-message, que encaminha para o caminho /webhooks acima. Se você mesmo executa o omni-message, o webhook listener dele deve estar acessível pela internet nestes caminhos: /webhooks/meta-messenger, /webhooks/instagram-business, /webhooks/wab-cloud, /webhooks/wab-gupshup/:channelId, /webhooks/wab-360-dialog/:channelId, /webhooks/telegram-bot/:channelId, /webhooks/tiktok e /webhooks/twilio-sms/:channelId (apps/webhook-listener/src/modules/webhook-listeners/webhook-listeners.controller.ts no omni-message). O próprio MonoChat deve estar acessível ao omni-message nos caminhos /webhooks acima.
Sistemas de pagamento
Os provedores de pagamento chamam de volta quando um cliente paga e depois enviam o cliente de volta ao MonoChat. Ambos precisam funcionar fora da sua rede.
| Conector | Caminhos sob o seu hookPath (paymentSystemConnectors.<name>.hookPath) |
|---|---|
| Stripe | /webhook/:clientId (POST), /return/success/:paymentSystemId, /return/cancel/:paymentSystemId |
| HyperPay | /pay/:clientId/:paymentSystemOrderId, /result/:clientId/:paymentSystemOrderId |
| Mamo | /webhook/:clientId (POST), /return/:clientId/:paymentSystemOrderId |
| Midtrans | /webhook/:clientId (POST), /return/:paymentSystemOrderId |
| Paymob | /webhook/:clientId (POST), /return/:paymentSystemOrderId |
| PayTabs | /callback/:clientId/:paymentSystemOrderId (POST), /return/:paymentSystemOrderId |
| Tabby | /webhook/:clientId (POST), /return/:paymentSystemOrderId/:status |
| Tamara | /webhook/:clientId (POST), /return/:paymentSystemOrderId/:status |
| Tap | /webhook/:clientId (POST), /return/:clientId/:paymentSystemOrderId |
| Telr | /webhook/:clientId/:paymentSystemOrderId (POST), /return/:paymentSystemOrderId/:status |
| Ziina | /return/:clientId/:paymentSystemOrderId/:status |
| iyzico | /:transactionId (POST) |
| JCC | /:status |
| MyFatoorah | o próprio hookPath (POST), /:paymentSystemOrderId/:status (POST) |
| N-Genius | o próprio hookPath (POST), /:paymentSystemOrderId/:status |
| Paywall | /:paymentSystemOrderId/:status |
| UniqoPay | o próprio hookPath (POST), /:paymentSystemOrderId/:status (POST) |
| VakıfBank Sanal POS | /:status (GET e POST) |
| İş Yerim POS | o próprio hookPath (GET e POST) |
A regra mais simples é abrir <hookPath> e tudo abaixo dele para cada conector de pagamento que você usa. Cada origem é packages/app-connectors-<name>/src/webhook.ts.
Outros endpoints do servidor
| Caminho | Usado para | Definido em |
|---|---|---|
/api/:slug/custom-functions/… (POST) | Chamar uma função personalizada por HTTP com um token de acesso | lib/managers/custom-function-sdk/_/server/endpoint.js |
/api/ai-agent/mcp, /api/ai-agent/events (POST) | Execuções do agente de IA que reportam de volta ao MonoChat | server/api/ai-agent.ts |
/api/channels-manager/facebook/auth, /api/channels-manager/tiktok/auth (GET) | A janela pop-up que retorna depois de conectar uma conta do Facebook ou do TikTok | packages/app-managers-channel/src/webhook.ts |
/l/:_id (GET) | Links curtos que você envia aos clientes | server/api/short-link.js |
/api/status (GET) | O aplicativo móvel verifica o servidor e suas opções de login | server/api/status.js |
/.well-known/assetlinks.json, /.well-known/apple-app-site-association (GET) | Links de aplicativo para Android e iOS | server/api/assetlinks.js, server/api/apple-app-site-association.js |
Abra /api/:slug/custom-functions, /api/ai-agent, /l/ e os dois caminhos de pop-up de canal se você usa esses recursos de fora da sua rede. Os caminhos de pop-up de canal são abertos no navegador da pessoa que conecta a conta, então podem continuar restritos se apenas pessoas da sua rede conectam canais. Abra /api/status e os dois arquivos /.well-known somente se os seus agentes usam o aplicativo móvel do MonoChat de fora da sua rede.
Login com um provedor (OAuth)
Quando um provedor de login redireciona o navegador de volta ao MonoChat, o redirecionamento é uma requisição normal do navegador de quem está fazendo login, portanto segue a mesma restrição do aplicativo web. Mantenha os caminhos de redirecionamento acessíveis para as pessoas que fazem login dessa forma. Os caminhos são os valores redirectPath em public.oauth.<provider> nas configurações do servidor (os exemplos padrão são /api/oauth/google/redirect, /api/oauth/microsoft/redirect, /api/oauth/facebook/redirect e /api/oauth/apple/redirect). O login com Apple devolve o navegador com um POST (responseMode: form_post), que o mesmo caminho aceita. Para o aplicativo móvel, o servidor também responde a /api/oauth/facebook/mobile, /api/oauth/microsoft/mobile e /auth/oauth-callback/<provider> (server/configs/oauth/mobile.ts).
Se você usa a integração com o Microsoft Marketplace, o caminho em microsoftMarketplace.redirectWebhookPath recebe a requisição do Microsoft Marketplace e deve estar acessível pela internet (server/configs/microsoft-marketplace/webook.ts).
Repasse o IP real do cliente pelo proxy
O MonoChat registra o IP do cliente para sessões e logs de status. Atrás de um proxy reverso ou balanceador de carga, ele vê o endereço do proxy, a menos que você repasse o real.
- Faça o nginx (ou o seu balanceador de carga) enviar o endereço original no cabeçalho
X-Forwarded-For, por exemploproxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;. - Defina a variável de ambiente
HTTP_FORWARDED_COUNTno servidor do MonoChat com o número de proxies na frente do aplicativo. Ela é lida pelo framework Meteor, não pelo código do MonoChat, então pertence às configurações de implantação e não ao JSON de configurações.
Verifique a sua configuração
- A partir de uma rede não permitida, abra o aplicativo web. O acesso deve ser recusado.
- A partir de uma rede permitida, faça login e abra a caixa de entrada. As mensagens devem carregar, o que prova que o endpoint WebSocket está aberto para você.
- Envie uma mensagem de teste para um canal conectado de fora da sua rede e confirme que ela chega à caixa de entrada.
- Crie um link de pagamento para um pequeno pedido de teste, pague e confirme que o pedido aparece como pago.
Teste os caminhos após cada alteração nas regras do proxy. Um caminho de webhook bloqueado não mostra erro no MonoChat: as mensagens e as confirmações de pagamento simplesmente deixam de chegar.