Echobell
App Store Google Play

Integrazione webhook - guida completa ai trigger HTTP

Integra i webhook di Echobell: metodi HTTP, variabili, modelli, header ed esempi concreti per ricevere avvisi immediati sul telefono.

I webhook sono il modo più versatile per attivare le notifiche di Echobell. Questa guida completa copre tutto quello che ti serve sapere per integrare avvisi basati su webhook nei tuoi sistemi, dai concetti di base agli usi più avanzati.

Che cos'è un webhook

Un webhook è il modo in cui un'applicazione fornisce informazioni in tempo reale ad altre applicazioni tramite callback HTTP. Immaginalo come un numero di telefono che dai a qualcuno: quando quella persona chiama il numero, il tuo telefono squilla. Nel mondo digitale funziona così: quando succede qualcosa in un sistema (un picco di CPU, una build fallita, un nuovo ordine), quel sistema invia una richiesta HTTP a un URL che hai fornito tu, cioè il webhook, e questo attiva un'azione nel tuo sistema.

Per esempio, quando l'uso della CPU del tuo server diventa troppo alto, il sistema di monitoraggio può chiamare l'URL webhook di Echobell, che a sua volta fa partire una notifica per avvisarti. Tutto questo avviene in automatico e in tempo reale, senza che tu debba controllare di continuo l'uso della CPU.

I webhook sono la base delle architetture a eventi e sono supportati praticamente da tutti i servizi cloud, gli strumenti di monitoraggio e le piattaforme SaaS moderne. Sono leggeri, veloci e non richiedono nessuna infrastruttura particolare dalla tua parte: basta un client HTTP.

Vantaggi dei webhook

  • Tempo reale: gli eventi fanno partire le notifiche all'istante, di solito entro 1-2 secondi
  • Universali: supportati da quasi tutti i servizi e i linguaggi di programmazione moderni
  • Flessibili: puoi passare dati personalizzati e creare notifiche ricche di contesto
  • Affidabili: si basano su HTTP, con codici di stato e gestione degli errori standard
  • Scalabili: nessun polling necessario, le notifiche partono solo quando l'evento accade

Panoramica

Ogni canale Echobell può essere configurato con un URL webhook univoco. Quando questo URL viene chiamato, il canale invia una notifica a tutti i suoi iscritti in base ai modelli di notifica configurati e alle variabili ricevute.

Formato dell'URL webhook

https://hook.echobell.one/t/{channel-token}

Trovi l'URL webhook del tuo canale nella schermata di dettaglio del canale, nell'app Echobell.

Inviare richieste webhook

I webhook di Echobell supportano sia il metodo GET sia il metodo POST:

Richiesta GET

Puoi passare le variabili tramite i parametri della query:

GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95

Richiesta POST

Con le richieste POST, invia le variabili in un body JSON:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}

Solo POST

Ogni canale ha un interruttore Solo POST nelle Impostazioni avanzate dell'app Echobell. È disattivato per impostazione predefinita.

Quando è attivo, solo POST può attivare il canale. Una GET all'URL webhook viene rifiutata con 405 Method Not Allowed e non viene inviata nessuna notifica:

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

Le richieste HEAD non sono interessate: rispondono 200 e non attivano mai una notifica, che Solo POST sia attivo o meno.

Attivalo quando l'URL webhook finisce in un posto che carica i link in automatico — un messaggio in chat, una pagina wiki, la barra degli indirizzi del browser — così l'anteprima o l'apertura dell'URL non possono far partire un avviso. Lascialo disattivato se qualcuno dei sistemi che ti chiamano attiva il canale con GET.

Variabili speciali

Echobell supporta una variabile speciale che aggiunge funzionalità alle tue notifiche:

  • externalLink: se inclusa nella richiesta, crea un link cliccabile nella vista dei record delle notifiche. Utile per rimandare a informazioni dettagliate o a risorse correlate.

Esempio con link esterno:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}

Variabili dei modelli

Le variabili passate tramite webhook si possono usare nei modelli delle notifiche con la sintassi {{variableName}}:

Title: Server {{server_name}} Alert
Body: CPU usage has reached {{cpu_usage}}%

Al momento dell'attivazione, questi modelli vengono riempiti con i valori forniti nella tua richiesta webhook.

Variabili di sistema per data e ora (UTC)

Oltre ai dati che invii tu, Echobell mette a disposizione variabili di sistema per data e ora in sola lettura, sempre disponibili nei modelli e nelle condizioni. Tutti i valori sono calcolati in UTC. Tra i campi piatti ci sono date, time, year, month, dayOfWeek, hour, minute e second. Altri — come sys.dayOfWeekName, sys.epochMs e sys.epochSeconds — sono disponibili solo nel namespace sys.. Consulta Condizioni per l'elenco completo e per alcuni esempi.

Casi d'uso più comuni

I webhook sono il metodo di attivazione più usato in Echobell e si rivelano particolarmente utili per:

DevOps e monitoraggio

  • Monitoraggio dei server: avvisi su CPU, memoria e spazio su disco da sistemi di monitoraggio come Prometheus o Grafana
  • Monitoraggio uptime: avvisi sulla disponibilità di siti e servizi da Uptime Kuma o UptimeRobot
  • Monitoraggio dei container: errori dei pod Docker e Kubernetes, limiti di risorse raggiunti
  • Aggregazione dei log: errori critici ed eccezioni dai sistemi di gestione dei log

Sviluppo e CI/CD

  • Notifiche sulle build: build fallite, risultati dei test e stato dei deploy da GitHub Actions o GitLab CI
  • Qualità del codice: errori di lint, vulnerabilità di sicurezza, variazioni della copertura del codice
  • Eventi sui repository: pull request, commit, release e attività dei collaboratori
  • Monitoraggio dei deploy: deploy riusciti, rollback e cambi di ambiente

Applicazioni aziendali

  • E-commerce: nuovi ordini, conferme di pagamento, avvisi di magazzino, aggiornamenti sulle spedizioni
  • CRM: nuovi lead, trattative chiuse, ticket di assistenza, interazioni con i clienti
  • Pagamenti: transazioni completate, richieste di rimborso, avvisi antifrode
  • Invio di moduli: moduli di contatto, risposte ai sondaggi, registrazioni completate

IoT e casa intelligente

  • Eventi della casa intelligente: sensori delle porte, rilevamento del movimento, variazioni di temperatura tramite Home Assistant
  • Dispositivi IoT: letture dei sensori, cambi di stato dei dispositivi, problemi di connettività
  • Sistemi di sicurezza: allarmi scattati, movimento rilevato dalle telecamere, eventi di controllo accessi
  • Monitoraggio ambientale: superamento delle soglie di temperatura, umidità e qualità dell'aria

Trading e finanza

  • Avvisi di mercato: movimenti di prezzo e indicatori tecnici da TradingView
  • Monitoraggio del portafoglio: variazioni delle posizioni, margin call, saldi dei conti
  • Eventi economici: uscita di notizie, trimestrali, cambi di sentiment del mercato

Consulta le nostre guide all'integrazione per le istruzioni di configurazione delle piattaforme più diffuse.

Best practice

Gestione degli errori

Non fidarti solo dello stato HTTP: controlla sempre il corpo JSON della risposta e il campo success:

  • 200 OK: la richiesta è arrivata. Controlla il body JSON: success: true significa che il canale è stato attivato, mentre success: false significa che la richiesta è stata accettata ma non è partita nessuna notifica (per esempio con un token di canale sconosciuto, che restituisce comunque HTTP 200).
  • 400 Bad Request: il token del canale ha una lunghezza sbagliata. Correggi l'URL webhook.
  • 405 Method Not Allowed: il canale ha Solo POST attivo e la richiesta non era una POST. Fai passare il chiamante a POST oppure disattiva l'impostazione.
  • 500 Server Error: problema temporaneo, riprova con un backoff esponenziale

Echobell non applica limiti di frequenza alle chiamate webhook, quindi non esiste una risposta 429. Dato che un token sconosciuto (ma di lunghezza valida) restituisce comunque 200 con success: false, basa sempre la tua logica sul campo JSON success e non sullo stato HTTP.

Limiti di frequenza

Lascia passare un intervallo ragionevole tra una chiamata webhook e l'altra, per non sovraccaricare il tuo sistema di notifiche:

  • Per il monitoraggio continuo, raggruppa più eventi in un'unica notifica
  • Usa le condizioni per filtrare gli eventi non critici
  • Valuta di aggregare gli eventi che arrivano a raffica (per esempio più errori in un breve intervallo)
  • Evita di inviare trigger duplicati a raffica, così gli avvisi critici restano affidabili

Sicurezza dei dati

Condividi gli URL webhook solo con sistemi e servizi affidabili:

  • Tratta gli URL webhook come dei segreti: danno accesso diretto all'invio delle notifiche
  • Non inserire gli URL webhook in repository pubblici e non condividerli in documentazione pubblica
  • Ruota gli URL webhook periodicamente o quando qualcuno lascia il team
  • Usa la funzione "Reimposta token" del canale per invalidare i vecchi URL in caso di compromissione
  • Valuta di conservare gli URL in variabili d'ambiente o in un sistema di gestione dei segreti

Nomi delle variabili

Usa nomi di variabile chiari e coerenti nelle tue chiamate webhook:

  • Usa nomi descrittivi: server_name invece di s o srv
  • Segui la stessa convenzione di denominazione in tutti i canali
  • Documenta quali variabili si aspettano i tuoi modelli
  • Verifica che tutte le variabili necessarie siano presenti prima di inviare

Test

Prova a fondo la tua integrazione webhook prima di metterla in produzione:

  1. Per le prime prove usa strumenti come curl, Postman o il client HTTP del tuo linguaggio
  2. Parti da modelli semplici e aggiungi complessità man mano
  3. Prova sia il metodo GET sia il metodo POST per capire quale funziona meglio nel tuo caso
  4. Verifica che i caratteri speciali e l'Unicode vengano gestiti correttamente
  5. Prova gli scenari di errore (variabili mancanti, JSON malformato) per capire come si comporta il sistema
  6. Durante lo sviluppo usa canali di test separati da quelli di produzione

Progettazione dei modelli

Progetta modelli che restino utili anche quando mancano le variabili facoltative:

  • Prevedi valori predefiniti o alternative per i dati facoltativi
  • Struttura i modelli in modo che gestiscano bene le variabili mancanti
  • Prova i modelli con varie combinazioni di variabili presenti e assenti
  • Usa le espressioni condizionali per le parti facoltative

Monitoraggio

Tieni sotto controllo le tue integrazioni webhook per assicurarti che funzionino a dovere:

  • Registra nella tua applicazione le chiamate webhook riuscite e quelle fallite
  • Tieni traccia dei tassi di consegna delle notifiche e dei tempi di risposta
  • Imposta degli avvisi per gli errori dei webhook o per i comportamenti anomali
  • Rivedi e prova periodicamente le integrazioni webhook più critiche

Privacy e sicurezza

Ecco come Echobell tratta i dati dei tuoi webhook:

Cosa viene memorizzato

  • Sui nostri server:

    • gli URL webhook (i token), necessari per instradare le richieste in arrivo verso i canali
    • le configurazioni dei canali: modelli, condizioni, impostazioni
    • le relazioni di iscrizione, cioè chi è iscritto a quale canale

  • Sul tuo dispositivo:

    • il contenuto della notifica, cioè il titolo e il testo generati
    • la cronologia dei trigger, con il momento in cui le notifiche sono arrivate
    • i valori delle variabili, cioè i dati passati nelle chiamate webhook
    • link e metadati, come externalLink e altri dati associati

Cosa non viene memorizzato

  • Non conserviamo in modo permanente i payload grezzi dei webhook
  • Non registriamo né tratteniamo i dati sensibili contenuti nelle tue richieste
  • Non analizziamo né elaboriamo il contenuto delle notifiche per nessuno scopo
  • Non condividiamo i dati dei tuoi webhook con terze parti

Consigli di sicurezza

  • Tratta gli URL webhook come chiavi API: permettono di inviare notifiche senza alcuna autenticazione
  • Ruota gli URL regolarmente: usa la funzione "Reimposta token" per generare nuovi URL
  • Usa client HTTPS: accettiamo solo connessioni HTTPS, ma assicurati che il tuo client verifichi i certificati
  • Verifica l'origine delle chiamate: se possibile, limita gli IP o i servizi autorizzati a chiamare i tuoi webhook
  • Tieni d'occhio gli abusi: fai attenzione a comportamenti anomali o a usi non autorizzati
  • Separa gli ambienti: usa canali diversi per sviluppo, staging e produzione

Scopri di più nella nostra documentazione di supporto.

Risoluzione dei problemi

Se i tuoi webhook non funzionano come previsto, prova questi passaggi diagnostici:

Il webhook non attiva le notifiche

  1. Verifica che l'URL webhook sia corretto

    • Copia l'URL direttamente dall'app Echobell
    • Assicurati che non siano stati aggiunti spazi o caratteri di troppo
    • Controlla di usare https://hook.echobell.one/t/ e non un altro dominio

  2. Controlla che il canale sia attivo

    • Apri il canale nell'app Echobell
    • Verifica che non sia stato eliminato o archiviato
    • Assicurati di non aver reimpostato il token del webhook (l'URL non sarebbe più valido)

  3. Assicurati che il payload JSON sia formattato correttamente (per le richieste POST)

    • Usa un validatore JSON per controllare il payload
    • Controlla che le stringhe siano racchiuse tra virgolette
    • Verifica che l'header Content-Type sia impostato su application/json

  4. Verifica di fornire tutte le variabili richieste dai tuoi modelli

    • Guarda nei modelli di notifica quali variabili vengono usate
    • Verifica che quelle variabili siano presenti nella richiesta webhook (parametri della query o body JSON)
    • Ricorda che le variabili mancanti vengono rese come stringhe vuote

  5. Controlla che il canale abbia iscritti attivi

    • Le notifiche partono solo se qualcuno è iscritto al canale
    • Verifica la tua iscrizione nell'elenco dei canali dell'app
    • Controlla che le iscrizioni non siano state rimosse per sbaglio

Le notifiche non vengono visualizzate correttamente

  1. I nomi delle variabili non corrispondono

    • Il modello usa {{server_name}} ma il webhook invia serverName
    • I nomi delle variabili distinguono maiuscole e minuscole e devono corrispondere esattamente
    • Controlla che non ci siano errori di battitura nei nomi

  2. I dati annidati non sono accessibili

    • Usa la notazione con il punto: {{user.name}}, oppure con le parentesi quadre: {{user["name"]}}
    • Verifica che la struttura del tuo JSON corrisponda a quella prevista dal modello
    • Prova prima con variabili semplici, non annidate, e solo dopo aggiungi l'annidamento

  3. Caratteri speciali che creano problemi

    • Codifica correttamente i parametri della query (URL encoding)
    • Applica l'escape ai caratteri JSON speciali nei body delle POST
    • Prova prima con del semplice testo ASCII

Provare la tua integrazione

Usa curl per provare il webhook direttamente:

# Test with query parameters
curl "https://hook.echobell.one/t/<channel-token>?test=hello&status=working"

# Test with JSON body
curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H "Content-Type: application/json" \
  -d '{"test": "hello", "status": "working"}'

Se tutto è configurato correttamente, dovresti ricevere subito una notifica.

Hai ancora problemi?

Se hai provato i passaggi qui sopra e le difficoltà persistono:

  • Visita il nostro Centro assistenza per altre guide alla risoluzione dei problemi
  • Controlla se ci sono problemi noti o aggiornamenti sullo stato del servizio
  • Scrivici a echobell@weelone.com indicando:
    • una descrizione del problema
    • i passaggi che hai già provato
    • un esempio di URL webhook (con il token rimosso o oscurato)
    • un esempio del payload della richiesta
    • il comportamento atteso e quello effettivo

Prossimi passi

Ora che sai come funziona l'integrazione webhook:

Vuoi integrare Echobell con i tuoi sistemi? Crea il tuo primo canale e inizia a ricevere notifiche istantanee!