Notifiche dirette - chiavi API personali per avvisi immediati

Le notifiche dirette ti permettono di inviare avvisi personali tramite un semplice URL webhook — senza configurare canali, senza modelli, senza iscritti. Basta creare una chiave, chiamare l'URL e ricevere subito la notifica sul tuo dispositivo.

Che cos'è Diretto?

I canali sono ottimi per notifiche strutturate e basate su modelli, che puoi condividere con altre persone. A volte però ti serve solo una notifica rapida e personale: una build finita, uno script completato, un sensore che si è attivato. Diretto nasce esattamente per questo.

Con Diretto ottieni una chiave API personale associata a un URL webhook univoco. Quando chiami quell'URL con un titolo e un testo, la notifica arriva direttamente a te. Nessuna configurazione di canale.

Quando usare Diretto e quando i canali

Primi passi

1. Crea una chiave diretta

Nell'app Echobell, tocca Diretto in cima all'elenco dei canali. Poi tocca Crea per generare una nuova chiave diretta. Dalle un nome descrittivo (ad esempio "Server di build", "Home Lab", "Trading Bot").

2. Copia l'URL webhook

Ogni chiave diretta ha un URL webhook univoco in questo formato:

https://hook.echobell.one/d/{your-key-token}

Puoi trovare e copiare questo URL dalla schermata di dettaglio della chiave diretta nell'app. Per sicurezza il token è nascosto per impostazione predefinita: tocca per mostrarlo.

3. Invia una notifica

Chiama l'URL webhook con un body JSON che contenga title e body:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Build Complete",
  "body": "Project X built successfully in 3m 42s"
}

Tutto qui: la notifica ti arriva immediatamente.

Inviare richieste

Richiesta POST (consigliata)

Invia un body JSON con il contenuto della notifica:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Deployment Status",
  "body": "v2.1.0 deployed to production",
  "externalLink": "https://dashboard.example.com/deploys/latest"
}

Richiesta GET

Puoi anche passare i parametri nella query string:

GET https://hook.echobell.one/d/YOUR_KEY_TOKEN?title=Alert&body=CPU+at+95%25

Solo POST

Ogni chiave diretta ha la propria impostazione Solo POST nell'app Echobell. È disattivata per impostazione predefinita.

Quando è attiva, solo POST può attivare quella chiave. Una GET al suo 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.

L'impostazione vale per singola chiave, quindi puoi tenere una chiave compatibile con GET per i one-liner da shell e una chiave solo POST per gli URL che finiscono incollati in chat o su pagine wiki.

Campi della richiesta

I nomi dei campi non fanno distinzione tra maiuscole e minuscole: title, Title e TITLE vengono trattati allo stesso modo, sia che li passi nel body JSON sia nella query string.

Tipi di notifica

Puoi controllare il livello di urgenza delle notifiche dirette con il campo notificationType:

Esempio con il tipo di notifica:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Server Down",
  "body": "Production server is unresponsive",
  "notificationType": "calling"
}

Formato della risposta

Una richiesta andata a buon fine restituisce:

{
  "success": true,
  "message": "Notification triggered successfully."
}

Se la chiave non è valida o non esiste (nota che la risposta HTTP resta 200):

{
  "success": false,
  "message": "Direct key not found."
}

Gestire le chiavi dirette

Più chiavi

Puoi creare più chiavi dirette per scopi diversi:

• "Server CI" — per le notifiche di build e di deploy
• "Domotica" — per gli avvisi dei sensori IoT
• "Cron job" — per i risultati delle attività pianificate
• "Trading Bot" — per gli avvisi di mercato

Ogni chiave ha il proprio URL webhook indipendente. I record delle notifiche vengono associati automaticamente alla chiave che li ha generati, così capisci al volo quale servizio ha inviato ogni notifica.

Reimposta il token

Se l'URL webhook di una chiave viene compromesso, puoi reimpostare il token dalla schermata di dettaglio della chiave. Viene generato un nuovo URL e quello vecchio smette di funzionare all'istante. Ricordati di aggiornare gli script e i servizi che usano il vecchio URL.

Elimina una chiave

Eliminando una chiave diretta, il suo URL webhook diventa definitivamente non valido. Tutte le richieste al vecchio URL falliranno.

Casi d'uso comuni

Script di shell

# Notify when a long-running task finishes
./run-migration.sh && \
curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"title": "Migration Complete", "body": "Database migration finished successfully"}'

Cron job

# In crontab: notify on backup completion
0 2 * * * /usr/local/bin/backup.sh && curl -s -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN -H "Content-Type: application/json" -d '{"title": "Backup Done", "body": "Nightly backup completed"}'

Python

import requests

requests.post(
    "https://hook.echobell.one/d/YOUR_KEY_TOKEN",
    json={
        "title": "Training Complete",
        "body": f"Model accuracy: {accuracy:.2%}",
        "externalLink": "https://wandb.ai/runs/abc123"
    }
)

Node.js

await fetch("https://hook.echobell.one/d/YOUR_KEY_TOKEN", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Deploy Complete",
    body: `Version ${version} deployed to production`,
  }),
});

GitHub Actions

- name: Notify via Echobell Direct
  if: always()
  env:
    ECHOBELL_DIRECT_URL: ${{ secrets.ECHOBELL_DIRECT_URL }}
  run: |
    curl -X POST "$ECHOBELL_DIRECT_URL" \
      -H "Content-Type: application/json" \
      -d '{"title": "Build ${{ job.status }}", "body": "${{ github.repository }} @ ${{ github.sha }}"}'

Best practice

Sicurezza

• Tratta gli URL delle chiavi dirette come segreti — chiunque abbia l'URL può inviarti notifiche
• Usa le variabili d'ambiente per conservare i token delle chiavi negli script e nelle pipeline CI/CD
• Reimposta i token appena sospetti che una chiave sia stata compromessa
• Crea chiavi separate per servizi diversi, così puoi revocarle una alla volta

Organizzazione

• Dai alle chiavi nomi descrittivi — te ne sarai grato quando ne avrai parecchie da gestire
• Usa una chiave per ogni servizio — così individui subito la fonte di una notifica e revochi solo quella
• Elimina le chiavi inutilizzate — riduci la superficie di attacco

Gestione degli errori

Quando integri Diretto nei tuoi script, basati sul campo JSON success invece che sullo stato HTTP:

• 200 OK: la richiesta è arrivata. Controlla il body JSON: success: true significa che la notifica è stata inviata, success: false che non è partita. Una chiave diretta sconosciuta o reimpostata risponde con HTTP 200 e { "success": false, "message": "Direct key not found." }, non con un 404.
• 400 Bad Request: il token della chiave ha una lunghezza sbagliata. Correggi l'URL.
• 405 Method Not Allowed: la chiave ha Solo POST attivo e la richiesta non era una POST. Fai passare il chiamante a POST oppure disattiva l'impostazione.

Echobell non applica limiti di frequenza alle chiamate dirette, quindi non esiste una risposta 429.

Privacy e sicurezza

Cosa viene memorizzato

• Sui nostri server:

  • i metadati della chiave diretta (nome, token con hash, proprietario)
  • il payload della richiesta, elaborato e conservato temporaneamente per la consegna

• Sul tuo dispositivo:

  • il contenuto della notifica (titolo e testo)
  • la cronologia dei trigger e i relativi orari
  • i link esterni

Cosa non viene memorizzato

• Non conserviamo in modo permanente i payload delle richieste dopo la consegna
• Non analizziamo il contenuto delle notifiche
• Non condividiamo i tuoi dati con terze parti

Risoluzione dei problemi

Non ricevi le notifiche

1. Verifica l'URL webhook — copialo direttamente dall'app e controlla che non ci siano spazi di troppo
2. Controlla che la chiave esista ancora — potrebbe essere stata eliminata o il token reimpostato
3. Verifica i permessi per le notifiche — l'app Echobell deve poter inviare notifiche sul tuo dispositivo
4. Fai una prova con curl — per escludere problemi del tuo client HTTP:

   curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
     -H "Content-Type: application/json" \
     -d '{"title": "Test", "body": "Hello from Direct"}'

Errori nelle richieste

• Errore di parsing JSON: assicurati che l'header Content-Type: application/json sia impostato e che il body sia JSON valido
• Chiave non trovata: un body con "success": false e "Direct key not found." significa che il token è stato reimpostato o che la chiave è stata eliminata (lo stato HTTP resta comunque 200)

Hai ancora problemi?

• Visita il nostro Centro assistenza per altro supporto
• Scrivici a echobell@weelone.com indicando:
  • una descrizione del problema
  • un esempio di richiesta (con il token oscurato)
  • il comportamento atteso e quello effettivo

Prossimi passi

• Integrazione webhook — per notifiche condivise e basate su modelli, tramite i canali
• Sintassi dei modelli — impara a usare i modelli di notifica dei canali
• Trigger via email — attiva le notifiche via email
• Esplora le integrazioni — collega gli strumenti che usi già