Passa al contenuto principale

🌐 Webhook Trigger

Il Webhook Trigger consente ai sistemi esterni di avviare flussi di lavoro in SmartFlow inviando dati tramite richieste API. Questo trigger è ideale per integrare SmartFlow con applicazioni di terze parti, consentendo un'automazione dinamica e senza soluzione di continuità delle attività.

pasted-image.png

📝 Trigger Details​

Name: Webhook
Category: Triggers

🔧 Parametri​

1. Webhook URL​

  • Tipo: string
  • Descrizione: L'URL dell'endpoint per il webhook per ricevere richieste in arrivo. Questo viene generato automaticamente per ogni flusso di lavoro che utilizza questo trigger.
  • Obbligatorio: Sì
  • Esempio: 
    https://api.smartflow.com/webhooks/{workflowId}

2. Payload​

  • Tipo: object
  • Descrizione: I dati inviati dal sistema esterno nel corpo della richiesta. Questo payload può includere campi personalizzati a seconda dell'integrazione.
  • Obbligatorio: Sì
  • Esempio: 
    {
      "event": "order_created",
      "orderId": "12345",
      "customer": {
        "name": "John Doe",
        "email": "john@example.com"
      }
    }

3. Headers​

  • Type: object
  • Description: Intestazioni opzionali che il sistema esterno potrebbe includere per scopi di autenticazione o metadati.
  • Required: No
  • Example: 
    {
      "Authorization": "Bearer your-api-key",
      "Content-Type": "application/json"
    }

🚀 Come Funziona​

  1. Configurazione dell'URL del Webhook:

    • Quando si crea un flusso di lavoro con un Trigger Webhook, SmartFlow genera un URL unico per il webhook.
    • Condividi questo URL con il sistema esterno per configurare la loro integrazione.

  2. Recupero della Chiave API:

    • Naviga su Impostazioni ChatModel.
    • Vai a Integrazione → Web.
    • Clicca su Copia Chiave API per recuperare il token di autenticazione necessario.

  3. Struttura del Payload:

    • I sistemi esterni inviano dati (payload) all'URL del webhook utilizzando una richiesta HTTP POST.
    • Il payload deve corrispondere alla struttura richiesta dal flusso di lavoro.

  4. Esecuzione del Trigger:

    • Quando il webhook riceve una richiesta valida, il flusso di lavoro associato viene attivato automaticamente.
    • SmartFlow elabora il payload, esegue le azioni definite e restituisce una risposta se necessario.

💡 Casi d'uso​

  1. Integrazione CRM:

    • Scenario: Un cliente crea un nuovo account nel tuo sistema CRM.
    • Webhook: Il CRM invia una richiesta POST a SmartFlow con i dettagli del cliente.
    • Workflow: Invia un'email di benvenuto e aggiunge il cliente alla tua lista di marketing.

  2. Gestione degli Ordini:

    • Scenario: Una piattaforma di e-commerce elabora un nuovo ordine.
    • Webhook: La piattaforma invia i dettagli dell'ordine a SmartFlow.
    • Workflow: Aggiorna l'inventario, invia un'email di conferma dell'ordine e notifica il magazzino.

  3. Monitoraggio degli Incidenti:

    • Scenario: Un sistema di monitoraggio rileva un errore critico.
    • Webhook: Il sistema invia un avviso a SmartFlow.
    • Workflow: Crea un rapporto di incidente e notifica il team di ingegneria.

🔍 Esempio di Configurazione​

Richiesta Webhook in Entrata​

URL:

https://api.smartflow.com/webhooks/abc123

Payload:

{
  "event": "user_registered",
  "userId": "67890",
  "name": "Jane Doe",
  "email": "jane@example.com"
}

Headers:

{
  "Authorization": "Bearer 123456789",
  "Content-Type": "application/json"
}

🛠️ Best Practices​

  1. Validation:

    • Validare le richieste in arrivo per garantire l'integrità dei dati e prevenire abusi.
    • Utilizzare intestazioni o token sicuri per l'autenticazione.

  2. API Key Security:

    • Assicurarsi che la chiave API recuperata da ChatModel Settings → Integration → Web sia mantenuta sicura e non esposta pubblicamente.

  3. Data Mapping:

    • Mappare chiaramente i campi in arrivo alle variabili del workflow per un'elaborazione senza soluzione di continuità.

  4. Testing:

    • Testare il webhook con payload di esempio per garantire compatibilità e affidabilità.

  5. Error Handling:

    • Configurare i workflow per gestire in modo elegante dati mancanti o malformati.

📊 Monitoraggio e Debugging​

  • Log delle Attività:
    Monitora le richieste webhook in arrivo e il loro stato di elaborazione nel dashboard di SmartFlow.

  • Segnalazione degli Errori:
    Identifica le richieste non riuscite e visualizza i dettagli degli errori per la risoluzione dei problemi.

Questa sezione fornisce una guida dettagliata per il Webhook Trigger, assicurando che gli utenti possano integrarlo senza problemi nei loro flussi di lavoro. Fammi sapere se hai bisogno di ulteriori perfezionamenti!