Un webhook permette a FlexiProject di avvisare un sistema esterno nel momento stesso in cui nella tua organizzazione accade qualcosa. Invece di interrogare continuamente l’API per vedere se qualcosa è cambiato, il tuo sistema riceve una richiesta HTTP con i dati dell’evento subito dopo che si è verificato.
Un webhook collega un evento a un indirizzo del destinatario. Per inviare due eventi diversi allo stesso indirizzo, o lo stesso evento a due sistemi, crea due webhook.
Configuri i webhook in Impostazioni del sistema > Webhook. La sezione è disponibile per gli amministratori di sistema (vedi Utenti e permessi). Per leggere i dati tramite un altro canale, usa l’API.
Eventi
FlexiProject segnala quattro eventi. Ogni webhook ascolta esattamente uno di essi, scelto dall’elenco Evento.
| Evento | Quando FlexiProject invia la richiesta | Dati specifici dell’evento |
|---|---|---|
| Progetto creato | È nato un nuovo progetto, in qualsiasi modo: da zero, da un modello, per clonazione, importando un file MS Project o Excel, oppure con l’aiuto dell’IA. | projectId, projectName, createdAt |
| Progetto eliminato | Un progetto è stato eliminato. | projectId, projectName |
| Accettazione avviata | Un cambio di baseline è stato inviato all’accettazione ed è partito il suo percorso di approvazione. | changeRequestId, changeRequestName, projectId, projectName, date |
| Accettazione completata | Il percorso di approvazione si è concluso con una decisione: accettazione, rifiuto o annullamento. | changeRequestId, changeRequestName, projectId, projectName, decisionDate, status |
Ogni richiesta contiene inoltre il nome dell’evento (event), il momento in cui è stata generata (timestamp), l’identificatore (userId) e l’indirizzo e-mail (userEmail) dell’utente la cui azione l’ha attivata. Il formato dell’intera richiesta è descritto in Formato della richiesta HTTP. Le accettazioni sono descritte in Accettazioni.
Configurare un webhook
Elenco dei webhook
La pagina Webhook mostra tutti i webhook dell’organizzazione in tre colonne: Evento, URL del destinatario e Descrizione. Quando non è definito nulla, compare il messaggio Nessun webhook.
Aggiungere un webhook
- Clicca sul pulsante di aggiunta sopra l’elenco. Si apre la finestra Aggiungi webhook.
- Scegli l’Evento. Per impostazione predefinita è selezionato Progetto creato.
- Inserisci l’URL del destinatario — l’indirizzo a cui FlexiProject invia la richiesta. Il campo è obbligatorio e richiede l’indirizzo completo, protocollo incluso, per esempio
https://example.com/hooks/flexiproject. Un indirizzo incompleto viene rifiutato con un messaggio di errore di elaborazione dei dati. - Facoltativamente, inserisci una Descrizione — una nota per il tuo team, visibile solo nell’elenco.
- Clicca su Salva.
Segreto
Subito dopo il salvataggio compare la finestra Segreto con il messaggio: Il webhook è stato creato. Di seguito trovi il segreto, che verrà mostrato una sola volta. Copialo e conservalo in un luogo sicuro. Il pulsante Copia mette il valore negli appunti (messaggio Copiato negli appunti), e tu lo salvi nel sistema ricevente. Il segreto firma ogni richiesta, così il destinatario può confermare che la richiesta proviene da FlexiProject (vedi Formato della richiesta HTTP).
Dopo la chiusura della finestra, il valore completo non è più disponibile in nessun punto dell’applicazione. In un webhook aperto in seguito, il campo Segreto mostra solo i primi e gli ultimi quattro caratteri con asterischi nel mezzo; il campo non è modificabile.
Modificare un webhook
Clicca sul nome di un evento nell’elenco per aprire la finestra Modifica webhook. Lì cambi l’evento, l’indirizzo del destinatario e la descrizione, poi clicca su Salva. Il segreto resta invariato — la modifica non ne genera mai uno nuovo. Chiudendo la finestra con modifiche non salvate compare la domanda Volete andare avanti e abbandonare il cambiamento?
Testare un webhook
Il pulsante Testa si trova nella finestra di modifica di un webhook salvato. Invia all’indirizzo configurato una richiesta nel formato dell’evento scelto, compilata con dati di esempio (per esempio un progetto di nome Test Project), e conferma con Richiesta di test inviata con successo. Il messaggio conferma che la richiesta è stata inviata, non che il destinatario l’ha accettata — controlla il risultato sul lato ricevente.
Eliminare un webhook
Il pulsante Cancellare nella finestra del webhook richiede di confermare la domanda Sei sicuro di voler eliminare il webhook? Da quel momento l’evento non viene più inviato a quell’indirizzo. L’eliminazione non può essere annullata; per riprendere la consegna serve un nuovo webhook, e quindi un nuovo segreto.
Formato della richiesta HTTP
FlexiProject invia all’indirizzo configurato una richiesta POST con un corpo JSON.
Intestazioni
| Intestazione | Contenuto |
|---|---|
X-FlexiProject-Event |
Il nome dell’evento: ProjectCreated, ProjectDeleted, AcceptanceStarted oppure AcceptanceCompleted. |
X-FlexiProject-Delivery |
L’identificatore della consegna. Resta lo stesso in tutti i nuovi tentativi dello stesso evento, quindi permette di riconoscere i duplicati. |
X-FlexiProject-Timestamp |
Il momento in cui la richiesta è stata inviata. |
X-FlexiProject-Signature |
La firma del corpo della richiesta nella forma sha256=<value>. |
Verificare la firma
La firma è un HMAC-SHA256 del corpo grezzo della richiesta, calcolato con il segreto del webhook come chiave e scritto in esadecimale minuscolo. Sul lato ricevente, calcola lo stesso valore dal corpo ricevuto e confrontalo con la parte dell’intestazione X-FlexiProject-Signature dopo sha256=. Se i valori sono diversi, rifiuta la richiesta — non proviene dalla tua organizzazione in FlexiProject.
Esempio di corpo
{
"projectId": "6712f0a1c3d4e5f601234567",
"projectName": "Warehouse modernization",
"createdAt": "2026-09-21T08:14:02Z",
"userId": "a3f1c7de-1b20-4f9e-9a55-0c2d8e7b41aa",
"userEmail": "anna.kowalska@example.com",
"event": "ProjectCreated",
"timestamp": "2026-09-21T08:14:02Z"
}Risposta e nuovi tentativi
Rispondi con uno stato di successo (2xx) non appena accetti la richiesta. Qualsiasi altra risposta, o l’assenza di risposta, conta come consegna non riuscita.
Una consegna non riuscita viene ritentata automaticamente a intervalli crescenti: dopo 1, 2, 4, 8, 16, 32, 64, 128, 256 e 512 minuti. I tentativi si estendono su circa diciassette ore, quindi un destinatario non disponibile per un certo tempo non perde l’evento. Ogni tentativo ripete lo stesso valore X-FlexiProject-Delivery, perciò prepara la tua gestione a ricevere più volte lo stesso evento.
