Cosa sono i WebHook
I WebHook sono notifiche automatiche che si attivano al verificarsi di specifici eventi definiti dall’utente.
Servono per collegare Starty ad applicazioni esterne senza bisogno di interventi manuali, permettendo quindi di attivare procedure esterne in modo immediato e automatizzato.
Il modulo Automazione consente di:
definire eventi e/o condizioni,
associare a tali eventi WebHook che verranno eseguiti automaticamente.
Modalità di esecuzione dei WebHook
Nel flusso di automazione esistono due modalità che determinano quante volte un’azione può essere eseguita:
Esegui una sola volta per ogni elemento
La sequenza di azioni viene creata solo la prima volta che la condizione risulta soddisfatta.
Verifiche successive per lo stesso record non produrranno ulteriori esecuzioni.Esegui tutte le volte che i criteri sono soddisfatti
La sequenza verrà eseguita ogni volta che la condizione è nuovamente verificata sullo stesso record.
Con questa distinzione si stabilisce se, per uno stesso record, la sequenza di azioni del flusso deve essere eseguita una sola volta o più volte.
Tipi di attivazione del flusso
Un flusso può essere attivato in due modi:
Ad ogni modifica dell’elemento
L’evento viene rilevato immediatamente alla creazione o modifica di un’entità (es. creazione anagrafica prodotto).Al verificarsi di una o più condizioni
La condizione viene verificata a intervalli regolari da un monitor.
Esempio: la variazione della giacenza di un prodotto, rilevata dopo la conferma di un documento (fattura, entrata merci), sarà intercettata non al momento della conferma, ma in un momento successivo determinato dalla scansione del monitor.
Queste due modalità rispondono a casi d’uso diversi:
"Ad ogni modifica dell’elemento" è ideale per rilevare aggiornamenti immediati di entità.
"Al verificarsi di una o più condizioni" è adatta a cambiamenti derivanti da processi indiretti, non rappresentabili come una semplice modifica dell’entità in questione.
Servizi coinvolti
I flussi di automazione si basano su tre servizi distinti:
Servizio eventi – gestisce l’attivazione Ad ogni modifica dell’elemento.
Servizio di monitoraggio – esegue i controlli periodici per la modalità Al verificarsi di una o più condizioni.
Servizio di esecuzione – recupera ed esegue azioni rimaste in stato Pendente, ad esempio a causa di errori precedenti.
Attivazione e gestione flussi
Dopo la creazione o modifica di un flusso, questo deve essere esplicitamente attivato.
Ogni modifica al flusso ne comporta la disattivazione, perciò è necessario riattivarlo manualmente.
Lo stato e l’esito delle esecuzioni possono essere consultati nella finestra Flussi di automazione, tramite il pulsante dedicato accanto a ciascun flusso.
Esempio pratico: Flusso WebHook su variazione giacenza prodotto
Nell'immagine seguente è illustrata la configurazione di un flusso di automazione che invia un WebHook quando viene rilevata una variazione della giacenza del prodotto.
Il flusso è impostato affinché sia valido per tutte le organizzazioni, con esecuzione ogni volta che i criteri sono soddisfatti, e viene attivato tramite monitoraggio continuo su eventi di modifica della giacenza (data aggiunta movimento magazzino post-scansione).
L’azione configurata è “Esegui un WebHook”, con chiamata HTTP POST verso l’URL specificato.
Questa impostazione consente di integrare processi esterni ogni qualvolta vengono registrati movimenti di magazzino che comportano una variazione nella disponibilità prodotto, garantendo automatismo e tracciabilità nelle operazioni di sincronizzazione con sistemi esterni.
Per testare un WebHook si consiglia di usare RequestBin (https://requestbin.net/sign-in) e verificare così il contenuto della chiamata.
Sicurezza e gestione chiamata esterna
Per utilizzare i webhook in Starty è necessario usare il protocollo HTTPS.
Passaggi da seguire per autenticare una chiamata potenzialmente ricevuta da Starty con il protocollo HTTPS:
1. Serializzare il payload (JSON) come stringa
2. Convertire la stringa UTF-8 in bytes e aggiungere la stringa UTF-8 in bytes del header X-StartyHook-Timestamp.
3. Calcolare il HmacSha256 dei bytes ottenuti nel punto 2
4. Codificare i bytes ottenuti al punto 3 in esadecimale
5. Confrontare l'uguaglianza tra l' HmacSha256 codificato in esadecimale con il valore del header X-StartyHook-Signature
6. Se l'uguaglianza del punto 5 è vera allora la chiamata arriva da Starty, altrimenti il chiamante non è attendibile.
esempio in c#
string jsonPayload = "serializazione del json payload ricevuto";
string timestampHeader = "valore del header X-StartyHook-Timestamp ricevuto";
string signatureHeader = "3b89e9a8a1b94c9d41b7be6971e79a04b8e17efaa1f2d592e5fc081fc7c76cee";
using (HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes("StartyHookSecret")))
{
byte[] jsonPayloadBytes = Encoding.UTF8.GetBytes(jsonPayload);
byte[] timestampHeaderBytes = Encoding.UTF8.GetBytes(timestampHeader);
byte[] buffer = new byte[jsonPayloadBytes.Length + timestampHeaderBytes.Length];
Buffer.BlockCopy(jsonPayloadBytes, 0, buffer, 0, jsonPayloadBytes.Length);
Buffer.BlockCopy(timestampHeaderBytes, 0, buffer, jsonPayloadBytes.Length, timestampHeaderBytes.Length);
byte[] hash = hmac.ComputeHash(buffer);
string calculatedSignature = BitConverter.ToString(hash).Replace("-", "");
if (signatureHeader.Equals(calculatedSignature, StringComparison.CurrentCultureIgnoreCase))
{
// Chiamata ricevuta da Starty
}
else
{
// Chiamata ricevuta da mittente sconosciuto
}
}
Struttura del payload
Il WebHook inviato da Starty ha come payload un JSON contenente:
id dell’entità
Nome dell’evento:
"create" → entità creata
"update" → entità modificata
"confirm" → documento confermato
"change" → proprietà modificata
"become" → proprietà assume un determinato valore
Contesto
Date di creazione e modifica dell’entità
Nome del workflow
Le API di Starty consentono di usare questi dati per recuperare le informazioni necessarie a gestire l’evento.
Risoluzione problemi comuni
Il workflow è stato eseguito ma il WebHook non viene chiamato
Verificare i parametri del WebHook nella sezione Azioni.
Dopo aver corretto i parametri, annullare l’esecuzione precedente per evitare che una run fallita resti in sospeso.