Guida passo passo alla configurazione dei Webhooks di Quire

Ultimo aggiornamento: 24 luglio 2026

Hai mai desiderato che le tue app potessero parlarsi automaticamente? È esattamente quello che fanno i webhooks! Pensali come dei messaggeri che avvisano il tuo server nel momento stesso in cui succede qualcosa nei tuoi progetti Quire, che si tratti di una nuova attività creata, di qualcuno che aggiorna un'assegnazione o che segna un'attività come completata.

In questa guida ti mostreremo come configurare i webhooks in modo che le tue applicazioni restino sincronizzate con Quire, senza che tu debba muovere un dito.

Come iniziare con i Webhooks di Quire?

Passo 1: crea la tua app Quire

Prima di tutto, ti serve un'app Quire. Se non ne hai ancora creata una, visita la nostra guida su Come creare un'app Quire con la Quire API e ti accompagneremo passo passo.

Passo 2: dì a Quire dove inviare gli aggiornamenti

Ora è il momento di configurare il tuo endpoint webhook nel portale Sviluppatore Apps Quire. Si tratta semplicemente dell'indirizzo web a cui vuoi che Quire invii le notifiche, qualcosa come http://myserver/hookhandler.

Pensalo come dare a Quire il tuo indirizzo postale, così sa dove recapitare le notizie.

Passo 3: iscriviti agli aggiornamenti

L'ultimo passaggio della configurazione consiste nel dire a Quire quali progetti o attività vuoi seguire. Lo fai aggiungendo la tua app come "follower" tramite la Quire API:

curl -H 'Authorization: Bearer {access_token}' -X PUT \
  -d '{"addFollowers":["app"]}' \
  https://quire.io/api/project/projectAOid

Nota importante: assicurati di aver già configurato il tuo URL webhook prima di questo passaggio. Senza di esso, aggiungere la tua app come follower non funzionerà.

Quando non ti servono più gli aggiornamenti, rimuovi semplicemente la tua app dall'elenco dei follower. È così semplice!

Per maggiori dettagli, consulta Aggiornare un progetto tramite OID nella nostra documentazione API.

Come funzionano i Webhooks dietro le quinte?

Cosa riceverai

Una volta completata la configurazione, Quire inizia a inviarti notifiche ogni volta che succede qualcosa nei tuoi progetti seguiti. Arrivano come richieste POST con tutti i dettagli racchiusi in un pacchetto JSON ben organizzato:

{
  "type": "notification",
  "secret": "your-app-secret",
  "data": {
    "type": 0, 
    "when": "2019-09-30T08:20:12.000Z",
    "what": {
      "oid": "YxjapXXRCOYxoaiCT4tT3OQm", 
      "id": 101,
      "name": "Brand new start"
    },
    "user": {
      "oid": "1AbDEFed2A5031BEDDweqmde",
      "id": "john.doer",
      "name": "John Doer"
    },
    "message": "<a href=\"https://quire.io/u/john.doer\">John Doer</a> added <a href=\"https://quire.io/w/MyProjects/101\">Brand new start</a>",
    "text": "John Doer added Brand new start",
    "url": "https://quire.io/w/MyProjects/101"
  } 
}

La sicurezza prima di tutto: verifica la fonte

Ogni webhook include la chiave segreta della tua app. È il tuo modo per confermare che il messaggio provenga davvero da Quire e non da qualcuno che finge di essere noi. Controlla sempre questo dato prima di elaborare qualsiasi informazione!

Rispondere a eventi diversi

Nei tuoi progetti accadono cose diverse, e vorrai gestirle in modo diverso. Ecco un esempio semplice di come rispondere in base a ciò che è successo:

switch(json["data"]["type"]) {
  case 0:
    // new task added
    log("New task: " + json["data"]["what"]["name"]);
    break;
  case 1:
    // task removed
    log(json["data"]["user"]["name"] + " deleted " + json["data"]["what"]["name"]);
    break;
}

Quali tipi di eventi invia Quire?

Quire può notificarti ogni genere di attività. Ecco alcune delle più comuni:

Vuoi l'elenco completo? Visita la nostra documentazione sui tipi di attività per vedere tutto quello che Quire può dirti.

Far sapere a Quire che hai ricevuto il messaggio

Quando il tuo webhook riceve una notifica, invia semplicemente uno stato di successo (qualsiasi valore tra 200 e 299). Questo dice a Quire: "Ricevuto, grazie!"

Se qualcosa va storto e invii un codice di stato diverso, nessun problema: Quire proverà a inviare di nuovo la notifica dopo 15 minuti, poi dopo 1 ora e infine dopo 1 giorno.

Per maggiori dettagli, consulta "Responding and Retries" nella nostra documentazione API.

Come gestire i Webhooks su più progetti?

Lavori con diversi progetti Quire sullo stesso server? Abbiamo due approcci flessibili per te:

Opzione 1: usa etichette personalizzate

Puoi aggiungere un'etichetta personalizzata quando ti iscrivi agli aggiornamenti del progetto:

curl -H 'Authorization: Bearer {access_token}' -X PUT \
  -d '{"addFollowers":["app|handleProjectA"]}' \
  https://quire.io/api/project/projectAOid

Quire includerà questa etichetta in ogni notifica webhook, rendendo facile identificare quale progetto l'ha inviata:

{
  "type": "notification",
  "team": "handleProjectA",
  "data": {
    // event details...
  }
}

Poi nel tuo codice puoi instradare le notifiche di conseguenza:

switch(json["data"]["type"]) {
  case 0:
    // new task added
    if (json["team"] == "handleProjectA") {
      log("ProjectA has a new task: " + json["data"]["what"]["name"]);
    }
    break;
}

Opzione 2: usa percorsi diversi

Preferisci tenere le cose separate? Configura un percorso unico per ogni progetto:

curl -H 'Authorization: Bearer {access_token}' -X PUT \
  -d '{"addFollowers":["app|/projectAUpdate"]}' \
  https://quire.io/api/project/projectAOid

In questo modo, Quire invia le notifiche a diversi sottopercorsi del tuo endpoint principale (come http://myserver/hookhandler/projectAUpdate), e puoi gestire ogni progetto con un handler dedicato.

Qual è la via più rapida al tuo primo webhook?

Ecco fatto! Ora sai come configurare i webhooks e mantenere le tue applicazioni perfettamente sincronizzate con Quire. Per la documentazione tecnica completa, consulta la sezione Webhook nella nostra documentazione API.

Stai sviluppando per un assistente AI invece che per un server personalizzato? Vedi Configurazione di Quire MCP in 5 minuti per collegare Claude, ChatGPT o qualsiasi client AI direttamente.

Buon lavoro!

Domande frequenti

Cos'è un webhook di Quire?

Una notifica HTTP automatica che Quire invia a un URL sotto il tuo controllo nel momento in cui accade qualcosa in un progetto seguito, così la tua app resta sincronizzata senza bisogno di polling.

Come configuro un webhook in Quire?

Crea un'app Quire, registra l'URL del tuo endpoint nel portale Sviluppatore Apps, poi aggiungi la tua app come follower del progetto tramite l'API. Configura l'URL prima di iscriverti, altrimenti la chiamata fallirà.

Come verifico che una richiesta webhook provenga davvero da Quire?

Ogni payload include il campo secret della tua app: confrontalo con il tuo secret memorizzato e rifiuta qualsiasi richiesta che non corrisponde.

Cosa succede se il mio server è offline quando scatta un webhook?

Quire ritenta tre volte: dopo 15 minuti, 1 ora e 1 giorno. Restituisci uno stato 2xx non appena ricevi il payload per interrompere ulteriori tentativi.

Come gestisco i webhooks per più progetti Quire sullo stesso server?

Puoi allegare un'etichetta personalizzata al momento dell'iscrizione (ad esempio app|handleProjectA) e instradare in base al campo team, oppure assegnare a ogni progetto un proprio sottopercorso sul tuo URL webhook.