Webhook¶

Avvertimento

È altamente consigliato consultare uno sviluppatore, un architetto di soluzioni o un altro ruolo tecnico quando si decide di utilizzare i webhook nonché durante l’intero processo di implementazione. Se non configurati correttamente, i webhook possono disturbare il database di Odoo e possono richiedere tempo per essere ripristinati.

I webhook, che possono essere creati in Studio, sono regole di automazione attivate da eventi esterni tramite callback HTTP definiti dall’utente. Quando un sistema esterno invia dati a un URL di Odoo webhook (il “trigger”) con un file di dati (il “payload”), Odoo risponde con un’azione predefinita nel database.

A differenza delle azioni programmate o delle chiamate API manuali, i webhook consentono la comunicazione e l’automazione in tempo reale. Ad esempio, se un ordine di vendita viene confermato in un sistema POS esterno, un webhook può aggiornare istantaneamente il magazzino di Odoo, garantendo la sincronizzazione del sistema.

Nota

Questa sezione spiega come creare un webhook che prende i dati da una fonte esterna. Tuttavia, è possibile creare anche un’azione automatizzata che invia una chiamata API a un webhook esterno.

Creare un webhook in Studio¶

I webhook possono essere configurati in Studio e la configurazione è divisa tra il trigger e le azioni.

Suggerimento

La configurazione di un webhook in Odoo non richiede coding al momento della connessione ai database Odoo ma il test richiede uno strumento esterno come Postman. Record o azioni di destinazione personalizzati possono richiedere competenze di programmazione.
Attiva la modalità sviluppatore per modificare il modello di destinazione del webhook (ad es. ordini di vendita o informazioni di contatto) e per trovare il nome tecnico del modello (che potrebbe richiedere una configurazione accurata del payload).

Configurare il trigger del webhook¶

Per creare un webhook con Studio, apri Studio, fai clic su Webhook e poi su Nuovo. Da qui, dai un nome al webhook, modificane il modello (il tipo di voce del database di destinazione) se necessario e di stabilire se le chiamate effettuate all’URL del webhook debbano essere registrate (in modo da tracciare la cronologia delle chiamate del webhook per la risoluzione dei problemi).

L’URL del webhook viene generato automaticamente. Questo è l’URL da utilizzare per testare il webhook e collegarlo al sistema esterno che invierà gli aggiornamenti al database.

Pericolo

L’URL del webhook è confidenziale e deve essere trattato con cura. Condividerlo online o senza precauzioni può fornire un accesso indesiderato al database di Odoo. Fai clic su Ruota secret per modificare l’URL, se necessario.

Infine, se il sistema che invia il webhook non è Odoo, sistema le azioni del Record di destinazione per cercare il record JSON incluso nel payload della chiamata API quando la chiamata viene effettuata all’URL del webhook. Se il sistema che invia il webhook è un database Odoo, assicurati che id e model appaiano nel payload.

Suggerimento

Sebbene il Modello venga configurato in Odoo, è il nome tecnico del modello che deve essere incluso nel payload. Passa con il mouse sul nome del modello, fai clic sull’icona (link interno) per trovare il nome tecnico nel campo Modello. Ad esempio, il webhook di un ordine di vendita usa il modello Ordine di vendita ma il nome tecnico sale.order viene utilizzato nel payload.

Nota

Al momento della creazione di un record nel database Odoo, il formato predefinito del record target non dovrebbe essere utilizzato, usa invece model.browse(i) o model.search(i).

Configurare l’azione di un webhook¶

Per configurare un’azione webhook durante la configurazione di un webhook, fai clic su Aggiungi un’azione nella scheda Azioni da eseguire. Fai clic sul Tipo di azione e configura i campi.

Testare il webhook¶

Nota

Per testare il webhook è necessario configurarlo, avere a disposizione un payload di prova da inviare al webhook e uno strumento o sistema esterno per inviare il payload tramite richiesta API POST. Puoi utilizzare uno strumento del tipo Postman che richiede meno competenze tecniche.

Se durante il test appare un messaggio che recita 200 OK oppure status: ok significa che il webhook funziona lato Odoo. Da qui, puoi iniziare l’implementazione con altri strumenti per inviare automaticamente le chiamate webhook a Odoo utilizzando l’URL del webhook.

Se vengono restituite altre risposte, il numero inviato nella risposta aiuta a identificare il problema. Ad esempio, un 500 Internal Server Error significa che Odoo non è riuscito a interpretare correttamente la chiamata. Se viene restituito, assicurati che i campi trovati nel file JSON siano mappati correttamente nella configurazione del webhook e nel sistema che invia la chiamata di prova. L’attivazione della registrazione delle chiamate nella configurazione del webhook fornisce un registro degli errori se il webhook non funziona come previsto.

Implementare il webhook¶

Una volta che il webhook è completamente configurato, collegalo al sistema che invia i dati al database di Odoo attraverso questo webhook. Assicurati che le chiamate API siano inviate all’URL del webhook quando si configura il sistema.

Casi d’uso webhook¶

Di seguito sono riportati due esempi di utilizzo dei webhook in Odoo. Questi webhook richiedono strumenti esterni (che sono elencati nell’esempio).

Avvertimento

Consulta uno sviluppatore, un architetto di soluzioni o un altro ruolo tecnico se decidi di implementare i webhook. Se non vengono configurati correttamente, i webhook possono disturbare il database di Odoo e possono richiedere tempo per essere ripristinati.

Aggiornare la valuta di un ordine di vendita¶

Il presente webhook permette di aggiornare la valuta di un ordine di vendita nell’applicazione Vendite in USD. È utile per le filiali al di fuori degli Stati Uniti con una società madre situata negli Stati Uniti o durante le fusioni quando si consolidano i dati in un unico database Odoo.

Configurare il trigger del webhook¶

Per configurare il webhook, apri l’app Vendite. In seguito, configura il trigger e il Modello viene impostato su Ordine di vendita. Successivamente, imposta il Record target su model.env[payload.get('model')].browse(int(payload.get('id'))). La ripartizione è la seguente:

model: ciò che viene aggiornato in Odoo (in questo caso, gli ordini di vendita). Questo corrisponde al Modello configurato precedentemente.
env: dove ha luogo l’azione. In questo caso, si tratta di Odoo.
payload: ciò che viene inviato all’URL del webhook. Questo contiene le informazioni che aggiornano l’ordine di vendita.
get(“model”): dice al webhook quale record del database guardare. In questo caso, il webhook recupera (get) i dati legati a un model specifico. In questo esempio, si tratta del modello Ordine di vendita.
browse: dice al webhook di controllare il model (Ordine di vendita) configurato dal payload per l’aggiornamento.
int: trasforma il target in un ``integer` (un numero intero). Questo è importante nel caso in cui alcune parole (una stringa) o un numero decimale siano inclusi nel record di destinazione del payload.
get(“id”): identifica il numero dell’ordine di vendita che viene aggiornato in Odoo.

Configurare l’azione di un webhook¶

Dopo aver configurato il trigger, configura l’azione del webhook facendo clic su Aggiungi azione. Per scegliere il Tipo, fai clic su Aggiorna record. Successivamente, seleziona Aggiorna, scegli il campo Valuta e seleziona USD per aggiornare il campo. Infine, fai clic su Salva e chiudi.

Riassunto configurazione webhook¶

Per riassumere ciò che è stato configurato, il webhook si rivolge agli ordini di vendita, identificati dal loro numero di ordine di vendita, e aggiorna la loro valuta in USD quando viene inviata una richiesta POST all’URL del webhook che include il numero dell’ordine di vendita (che è identificato dal record id del payload).

Testare il webhook¶

Testa la configurazione del webhook per assicurarti che tutto sia corretto. Per inviare il trigger simulato, il processo utilizza uno strumento chiamato Postman.

Questa sezione illustra i passaggi per testare il webhook in Postman, ma non offre assistenza in caso di problemi con lo strumento. Per ottenere assistenza specifica con Postman, contatta il loro team di supporto.

Una volta aperto Postman, crea una nuova richiesta HTTP e imposta il metodo su POST. Successivamente, copia l’URL del webhook da testare e incollalo nel campo URL di Postman. In seguito, fai clic sulla scheda Body e seleziona l’opzione raw. Imposta il tipo di file su JSON, quindi copia questo codice e incollalo nel file.

{
    "model": "sale.order",
    "id": "SALES ORDER NUMBER"
}

Da qui, scegli un ordine di vendita su cui testare il webhook. Se non è possibile eseguire il test in un database Odoo attivo, puoi creare un database demo con un ordine di vendita campione e il webhook configurato. Sostituisci SALES ORDER NUMBER con il numero dell’ordine di vendita senza la S o gli zeri prima del numero. Ad esempio, un ordine di vendita con il numero S00007 deve essere inserito come 7 in Postman. Infine, fai clic su Invia in Postman.

Se viene restituito un messaggio che dice 200 OK o status: ok, allora il webhook funziona correttamente dal lato di Odoo. La valuta dell’ordine di vendita di prova viene aggiornata. Da qui, si può iniziare l’implementazione con l’altro strumento per inviare automaticamente le chiamate webhook a Odoo utilizzando l’URL del webhook.

Se vengono restituite altre risposte, il numero a esse associato aiuta a identificare il problema. Ad esempio, un 500 Internal Server Error significa che Odoo non è riuscito a interpretare correttamente la chiamata. Se questo viene restituito, assicurati che i campi model e id siano mappati correttamente nella configurazione del webhook e in Postman.

Creare un nuovo contatto¶

Questo webhook utilizza un codice personalizzato per creare un nuovo contatto in un database Odoo. Potrebbe essere utile per creare automaticamente nuovi fornitori o clienti.

Configurare il trigger del webhook¶

Per configurare questo webhook, apri l’app Contatti. In seguito, configura il trigger e imposta il Modello su Contatto. Inoltre, imposta il Record target su model.browse([2]). La suddivisione è la seguente:

model: ciò che viene aggiornato in Odoo (in questo caso, contatto). Questo corrisponde al Modello configurato precedentemente.
browse: dice al webhook di controllare il model (i contatti) configurato dal payload per la creazione.

Configurare l’azione di un webhook¶

Dopo aver configurato il trigger, imposta l’azione del webhook facendo clic su Aggiungi azione. Per il Tipo, fai clic su Esegui codice, quindi configura il campo code con il codice di esempio qui sotto. Infine, fai clic su Salva e chiudi.

# variables to retrieve and hold data from the payload
contact_name = payload.get('name')
contact_email = payload.get('email')
contact_phone = payload.get('phone')

# a Python function to turn the variables into a contact in Odoo
if contact_name and contact_email:
    new_partner = env['res.partner'].create({
        'name': contact_name,
        'email': contact_email,
        'phone': contact_phone,
        'company_type':'person',
        'customer_rank': 1,
    })
# an error message for missing required data in the payload
else:
    raise ValueError("Missing required fields: 'name' and 'email'")

Riassunto configurazione webhook¶

Per riassumere ciò che è stato configurato, il webhook crea un contatto quando una chiamata API viene inviata all’URL del webhook che include le informazioni del contatto.

Testare il webhook¶

Testa la configurazione del webhook per assicurarti che tutto sia corretto. Per inviare il trigger simulato, il processo utilizza uno strumento chiamato Postman.

Una volta aperto Postman, crea una nuova richiesta e imposta il metodo su POST. Successivamente, copia l’URL del webhook da testare e incollalo nel campo URL di Postman. In seguito, fai clic sulla scheda Body e poi du raw. Imposta il tipo di file su JSON, quindi copia questo codice e incollalo nel file.

{
    "name": "CONTACT NAME",
    "email": "CONTACTEMAIL@EMAIL.COM",
    "phone": "CONTACT PHONE NUMBER"
}

Sostituisci i campi precedenti con le informazioni di un nuovo contatto in Postman e poi fai clic su Invia.

Se viene restituito un messaggio che dice 200 OK o status: ok, allora il webhook funziona correttamente dal lato di Odoo. Il nuovo contatto di prova appare nell’app Contatti. Da qui, si può iniziare l’implementazione con l’altro strumento per inviare automaticamente le chiamate webhook a Odoo utilizzando l’URL del webhook.

Se vengono restituite altre risposte, il numero a esse associato aiuta a identificare il problema. Ad esempio, un 500 Internal Server Error significa che Odoo non è riuscito a interpretare correttamente la chiamata. Se questo viene restituito, assicurati che i campi nel file JSON sia mappati correttamente nella configurazione del webhook e in Postman.

Edit on GitHub