Limitare un'installazione on-premise tramite IP
Questa pagina è destinata agli operatori di un'installazione on-premise di MonoChat. Spiega come limitare l'app web alle vostre reti a livello di rete (nginx o firewall) senza bloccare i servizi che devono chiamare MonoChat da internet.
MonoChat non ha una propria allowlist di IP. La restrizione si trova nel vostro nginx, load balancer o firewall e vale per l'intera installazione, non per un singolo tenant.
Cosa limitare e cosa lasciare aperto
| Da limitare alle vostre reti | Da lasciare raggiungibile da internet |
|---|---|
| L'app web e tutto ciò che non è elencato a destra | I percorsi di webhook e callback nelle tabelle seguenti |
L'endpoint DDP/WebSocket a cui si connette l'app web (/websocket) |
Limitate insieme l'interfaccia web e l'endpoint WebSocket: l'app usa entrambi. Per tutti gli altri consentite solo i percorsi seguenti e bloccate il resto.
Percorsi chiamati dai servizi esterni
Ogni percorso seguente è registrato dal server MonoChat. Un percorso costruito da un'impostazione è l'hookPath configurato sul server (in channelConnectors.<name> o paymentSystemConnectors.<name> nelle impostazioni del server); il suffisso viene aggiunto dal codice. Aprite solo i connettori che usate.
Canali
| Percorso | Chiamato da | Definito in |
|---|---|---|
<hookPath>/webhooks (POST) | omni-message, per WhatsApp Cloud, WhatsApp Gupshup, Instagram, Messenger, Telegram, TikTok, Twilio SMS e Varan OTP | packages/app-connectors-om2-*/src/webhooks/webhook.ts; hookPath from channelConnectors.whatsappBusinessVegaCloud, whatsappBusinessVegaGupshup, instagramCastor, messengerRigel, telegramBotRegulus, tikTokTimir, twilioSms, varanOtp |
<hookPath>/webhooks, <hookPath>/sessions, <hookPath>/messages (POST) | I vostri sistemi, tramite il canale 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) | Il provider SIP (canali generic SIP e Sonitel SIP) | channelConnectors.genericSip.hookPath, channelConnectors.sonitelSip.hookPath |
/api/facebook/channels/:channelId/flows/:flowId (POST) | WhatsApp, per WhatsApp Flows | server/api/whatsapp-flow.js |
The channel providers (Meta, Telegram, TikTok, Twilio) do not call MonoChat directly. They call the omni-message webhook listener, which forwards to the /webhooks path above. If you run omni-message yourself, its webhook listener must be reachable from the internet on these paths: /webhooks/meta-messenger, /webhooks/instagram-business, /webhooks/wab-cloud, /webhooks/wab-gupshup/:channelId, /webhooks/wab-360-dialog/:channelId, /webhooks/telegram-bot/:channelId, /webhooks/tiktok and /webhooks/twilio-sms/:channelId (apps/webhook-listener/src/modules/webhook-listeners/webhook-listeners.controller.ts in omni-message). MonoChat itself must be reachable from omni-message on the /webhooks paths above.
Sistemi di pagamento
I provider di pagamento richiamano MonoChat quando un cliente paga e poi rimandano il cliente a MonoChat. Entrambi devono funzionare dall'esterno della vostra rete.
| Connettore | Percorsi sotto il suo 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 | the hookPath itself (POST), /:paymentSystemOrderId/:status (POST) |
| N-Genius | the hookPath itself (POST), /:paymentSystemOrderId/:status |
| Paywall | /:paymentSystemOrderId/:status |
| UniqoPay | the hookPath itself (POST), /:paymentSystemOrderId/:status (POST) |
| VakıfBank Sanal POS | /:status (GET and POST) |
| İş Yerim POS | the hookPath itself (GET and POST) |
La regola più semplice è aprire <hookPath> e tutto ciò che si trova sotto per ogni connettore di pagamento che usate. Ogni sorgente è packages/app-connectors-<name>/src/webhook.ts.
Altri endpoint del server
| Percorso | Usato per | Definito in |
|---|---|---|
/api/:slug/custom-functions/… (POST) | Chiamata di una custom function via HTTP con un token di accesso | lib/managers/custom-function-sdk/_/server/endpoint.js |
/api/ai-agent/mcp, /api/ai-agent/events (POST) | Le esecuzioni dell'agente AI che riportano a MonoChat | server/api/ai-agent.ts |
/api/channels-manager/facebook/auth, /api/channels-manager/tiktok/auth (GET) | Il pop-up che ritorna dopo aver collegato un account Facebook o TikTok | packages/app-managers-channel/src/webhook.ts |
/l/:_id (GET) | I link brevi che inviate ai clienti | server/api/short-link.js |
/api/status (GET) | L'app mobile verifica il server e le sue opzioni di accesso | server/api/status.js |
/.well-known/assetlinks.json, /.well-known/apple-app-site-association (GET) | App link per Android e iOS | server/api/assetlinks.js, server/api/apple-app-site-association.js |
Aprite /api/:slug/custom-functions, /api/ai-agent, /l/ e i due percorsi dei pop-up dei canali se usate queste funzionalità dall'esterno della vostra rete. I percorsi dei pop-up dei canali si aprono nel browser della persona che collega l'account, quindi possono restare limitati se i canali vengono collegati solo da persone della vostra rete. Aprite /api/status e i due file /.well-known solo se i vostri agenti usano l'app mobile di MonoChat dall'esterno della vostra rete.
Accesso con un provider (OAuth)
Quando un provider di accesso reindirizza il browser a MonoChat, il reindirizzamento è una normale richiesta del browser della persona che accede, quindi segue la stessa restrizione dell'app web. Mantenete raggiungibili i percorsi di reindirizzamento per chi accede in questo modo. I percorsi sono i valori redirectPath in public.oauth.<provider> nelle impostazioni del server (gli esempi predefiniti sono /api/oauth/google/redirect, /api/oauth/microsoft/redirect, /api/oauth/facebook/redirect e /api/oauth/apple/redirect). L'accesso con Apple rimanda il browser con una POST (responseMode: form_post), che lo stesso percorso accetta. Per l'app mobile, il server risponde anche a /api/oauth/facebook/mobile, /api/oauth/microsoft/mobile e /auth/oauth-callback/<provider> (server/configs/oauth/mobile.ts).
Se usate l'integrazione Microsoft Marketplace, il percorso in microsoftMarketplace.redirectWebhookPath riceve la richiesta di Microsoft Marketplace e deve essere raggiungibile da internet (server/configs/microsoft-marketplace/webook.ts).
Passare l'IP reale del client attraverso il proxy
MonoChat registra l'IP del client per le sessioni e i log di stato. Dietro un reverse proxy o un load balancer vede l'indirizzo del proxy, a meno che non venga inoltrato quello reale.
- Fate in modo che nginx (o il vostro load balancer) invii l'indirizzo originale nell'intestazione
X-Forwarded-For, ad esempioproxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;. - Impostate la variabile d'ambiente
HTTP_FORWARDED_COUNTsul server MonoChat al numero di proxy davanti all'app. È letta dal framework Meteor, non dal codice di MonoChat, quindi va nelle impostazioni di deployment e non nel JSON delle impostazioni.
Verificare la configurazione
- Da una rete non consentita, aprite l'app web. L'accesso deve essere rifiutato.
- Da una rete consentita, accedete e aprite l'inbox. I messaggi devono caricarsi, il che dimostra che l'endpoint WebSocket è aperto per voi.
- Inviate un messaggio di prova a un canale collegato dall'esterno della vostra rete e verificate che arrivi nell'inbox.
- Create un link di pagamento per un piccolo ordine di prova, pagatelo e verificate che l'ordine risulti pagato.
Verificate i percorsi dopo ogni modifica alle regole del proxy. Un percorso webhook bloccato non mostra alcun errore in MonoChat: i messaggi e le conferme di pagamento semplicemente smettono di arrivare.