Marketplace delle Integrazioni

A cosa serve

• Scoprire integrazioni pre-confezionate con sistemi popolari (SAP PM, Maximo, Slack, Teams, ecc.) in un unico posto.
• Installare un'integrazione con un click invece di assemblarla a mano con webhook.
• Disinstallare con pulizia automatica delle risorse create.

Come funziona

Ogni integrazione del marketplace è un pacchetto con: prompt dell'agente, webhook configurati, field mapping e permessi richiesti. All'installazione Rela crea le risorse necessarie e le lascia attive. Alla disinstallazione le pulisce tutte — nessun webhook orfano o agente zombie.

Catalogo delle Integrazioni

Il marketplace offre integrazioni pre-costruite organizzate per categoria. Consulta il catalogo tramite GET /api/v1/integrations/marketplace:

GET /api/v1/integrations/marketplace?search=slack&category=communication&protocol=rest

Parametri di ricerca:

• search — Ricerca per nome o descrizione
• category — Filtra per categoria (communication, monitoring, erp, crm, iot)
• protocol — Filtra per protocollo (rest, graphql, mqtt, websocket, grpc)

Ogni integrazione nel catalogo include:

{
  "id": "slack-notifications",
  "name": "Slack Notifications",
  "category": "communication",
  "protocol": "rest",
  "description": "Send alerts and reports to Slack channels",
  "config_schema": { ... },
  "tool_templates": [ ... ],
  "version": "1.2.0"
}

Installare un'Integrazione

Per installare un'integrazione dal marketplace:

POST /api/v1/integrations/marketplace/{integration_id}/install
{
  "config": {
    "webhook_url": "https://hooks.slack.com/services/...",
    "channel": "#alerts",
    "notify_on": ["critical", "warning"]
  }
}

Il processo di installazione:

1. La configurazione viene validata contro il config_schema dell'integrazione
2. Vengono creati gli strumenti definiti in tool_templates
3. Le credenziali vengono archiviate in Secret Manager
4. L'integrazione viene attivata per il tenant
5. Viene eseguito un test di connettività

Se la validazione fallisce, viene restituito HTTP 422 con i campi non validi.

Disinstallazione con Pulizia

La disinstallazione rimuove tutte le risorse associate:

DELETE /api/v1/integrations/marketplace/{integration_id}/uninstall

Il processo pulisce:

• Strumenti creati dai template
• Credenziali archiviate
• Webhook registrati
• Configurazione dell'integrazione

Gli strumenti creati manualmente dall'utente non vengono rimossi.

Webhook in Entrata

Le integrazioni possono ricevere dati esterni tramite webhook:

POST /api/v1/integrations/webhooks/inbound/{webhook_id}
X-Webhook-Secret: {secret}

Validazione di sicurezza:

• Ogni webhook ha un segreto univoco generato alla creazione dell'integrazione
• L'header X-Webhook-Secret viene validato contro il segreto archiviato
• Opzionalmente viene validata la firma HMAC del payload
• Le richieste senza segreto valido ricevono HTTP 401

Il payload del webhook viene elaborato secondo le regole definite nell'integrazione, potendo generare eventi, creare attività o eseguire strumenti.

Interpolazione dei Template

I template degli strumenti utilizzano l'interpolazione per valori dinamici:

{
  "url": "{{config.base_url}}/api/messages",
  "headers": {
    "Authorization": "Bearer {{secrets.api_token}}"
  },
  "body": {
    "channel": "{{config.channel}}",
    "text": "{{input.message}}"
  }
}

Variabili disponibili:

• {{config.*}} — Valori di configurazione dell'integrazione
• {{secrets.*}} — Credenziali archiviate in modo sicuro
• {{input.*}} — Parametri forniti durante l'esecuzione dello strumento
• {{tenant.*}} — Dati del tenant (nome, ID)

L'interpolazione viene risolta al momento dell'esecuzione, senza mai esporre i segreti nella configurazione archiviata.

Benefici chiave

• Installazione in un click — nessuna config manuale pezzo per pezzo.
• Disinstallazione pulita — niente risorse orfane.
• Catalogo curato con integrazioni verificate contro versioni stabili.
• Webhook inbound + outbound pre-configurati con l'auth corretta.
• Versione mostrata esplicitamente — sai quale versione SAP/Maximo è supportata.