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 Odoo Studio, ti permettono di automatizzare un’azione nel tuo database Odoo quando si verifica un evento specifico in un altro sistema esterno.

In pratica, funziona come segue: quando l’evento si verifica nel sistema esterno, un file dati (il «payload») viene inviato all’URL del webhook di Odoo tramite una richiesta API `POST`e l’azione predefinita viene eseguita nel tuo database Odoo.

A differenza delle azioni programmate, che vengono eseguite secondo intervalli predefiniti o delle richieste API manuali che devono essere invocate esplicitamente, i webhook abilitano comunicazione e automazione in tempo reale e basate sugli eventi. Ad esempio, è possibile configurare un webhook per avere i dati del tuo magazzino Odoo aggiornati automaticamente al momento della conferma di un ordine di vendita in un sistema punto vendita esterno.

La configurazione di un webhook in Odoo non richiede programmazione se vengono connessi due database Odoo, ma il test di un webhook richiede uno strumento esterno. Record target o azioni personalizzati potrebbero richiedere competenze in materia di programmazione.

Nota

Questo articolo spiega come creare un webhook che riceve dati da una fonte esterna. Tuttavia, è anche possibile creare un’azione automatizzata che invia dati a un webhook esterno quando si verifica un cambiamento nel tuo database Odoo.

Creare un webhook in Odoo¶

Importante

Prima di implementare un webhook in un database live, configuralo e testalo utilizzando un database duplicato per assicurarti che il webhook funzioni come previsto.

Suggerimento

L’attivazione della modalità sviluppatore prima della creazione di un webhook fornisce grande flessibilità nella selezione del modello bersaglio della regola di automazione. Inoltre, ti permette di trovare il nome tecnico del modello e dei campi che potrebbero essere necessari per configurare il payload.

Per trovare il nome tecnico di un modello, con la modalità sviluppatore attivata, passa con il mouse sul nome del modello e poi fai clic su (link interno). Il nome tecnico può essere trovato nel campo Modello. Ad esempio, il webhook di un ordine di vendita utilizza il modello Ordine di vendita ma il nome tecnico sale.order viene utilizzato nel payload.

Per creare un webhook in Studio, procedi come segue:

apri Studio e fai clic su Webhook`e poi su :guilabel:`Nuovo
scegli un nome chiaro e significativo per il webhook che permette di identificarne lo scopo
se necessario, e ammesso che la modalità sviluppatore sia attiva, seleziona il Modello appropriato dal menu a tendina. Se la modalità sviluppatore non è stata attivata, la regola di automazione avrà come target il modello attuale per impostazione predefinita
l’URL del webhook viene generato automaticamente ma può essere modificato se necessario facendo clic su Ruota secret. Questo è l’URL che dovrebbe essere utilizzato durante l’implementazione del webhook stesso in un sistema esterno che invierà aggiornamenti al database

Avvertimento
L’URL è riservato e deve essere trattato con cautela. La condivisone dello stesso online o senza attenzione può fornire involontariamente l’accesso al database Odoo. Se l’URL viene aggiornato dopo l’implementazione iniziale, assicurati di aggiornarlo nel sistema esterno.
se lo desideri, attiva la funzione Registra chiamate per monitorare la cronologia delle richieste API inviate all’URL del webhook come, ad esempio, la rilevazione di problemi
se il sistema che invia il webhook non è Odoo, rettifica il codice del Record target affinché cerchi il record JSON incluso nel payload quando la richiesta API viene effettuata all’URL del webhook. Se il sistema che invia il webhook è un database Odoo, assicurati che id e model siano presenti nel payload.

Se il webhook viene utilizzato per creare record nel database Odoo, usa model.browse(i) oppure model.search(i) invece del formato predefinito Record target.
fai clic su Aggiungi un’azione nella scheda Azioni da eseguire per definire le azioni da eseguire
prima di implementare il webhook nel sistema esterno, testalo per assicurarti che funzioni come previsto.

Suggerimento

È possibile creare i webhook anche tramite il menu Automazioni in Studio selezionando il trigger Sul webhook.
Per accedere alla cronologia delle richieste API, se hai attivato la funzione Registra chiamate, fai clic sul pulsante Registri nella parte alta del modulo Regole di automazione.
Se lo scopo del webhook è qualcosa di diverso dall’aggiornamento di un record esistente, ad es. creare un nuovo record, è necessario scegliere l’azione Esegui codice.

Testare un webhook¶

Il test di un weebhook richiede un payload di prova e uno strumento o sistema esterno, come Postman, per inviare il payload tramite una richiesta API POST. Questa sezione illustra gli step da seguire per testare un webhook in Postman.

Suggerimento

Consulta la sezione casi d’uso webhook per delle spiegazioni step-by-step su come testare i webhook utilizzando payload di prova.
Per ottenere aiuto specifico durante il test di un webhook con Postman, è possibile contattare il team di supporto.

In Postman, crea una nuova richiesta HTTP e configura il metodo su POST.
Copia l’URL del webhook dal database Odoo utilizzando l’icona (link) e incollalo nel campo URL in Postman.
Fai clic sulla scheda Corpo e seleziona raw (senza elaborazione).
Imposta il tipo di file su JSON e poi copia il codice dal payload di prova e incollalo nell’editor del codice.
Fai clic su Invia.

Nel visualizzatore delle risposte nella parte inferiore dello schermo su Postman, i dettagli, compreso un codice di risposta HTTP, indicano se il webhook funzioni correttamente o meno.

Un messaggio come 200 OK o status: ok indica che il webhook funziona correttamente lato Odoo. Da qui, è possibile avviare l’implementazione con l’altro sistema per inviare automaticamente le richieste API all’URL del webhook Odoo.
Se viene restituita un’altra risposta, il numero associato a essa aiuta a individuare il problema. Ad esempio, il messaggio 500 Internal Server Error indica che Odoo non è riuscito a interpretare la chiamata in modo appropriato. In questo caso, assicurati che i campi presenti nel file JSON siano mappati correttamente nella configurazione del webhook e nel sistema che invia la chiamata di prova.

Suggerimento

L’attivazione della registrazione delle chiamate nella configurazione del webhook in Odoo fornisce i registri degli errori se il webhook non funziona come previsto.

Implementare un webhook in un sistema esterno¶

Una volta creato e testato con successo il webhook in Odoo, implementalo nel sistema che invia i dati al database Odoo, assicurandoti che le richieste API POST vengano inviate all’URL del webhook.

Casi d’uso webhook¶

Di seguito, trovi due esempi su come utilizzare i webhook in Odoo. Un payload di prova viene fornito per ogni esempio e può essere trovato nella sezione corrispondente quando si testa il webhook. Postman viene utilizzato per inviare il payload di prova.

Aggiornare la valuta di un ordine di vendita¶

Questo webhook aggiorna un ordine di vendita nell’app Vendite in USD quando il sistema esterno invia una richiesta API POST all’URL del webhook che include il numero dell’ordine di vendita (identificato dal record id del payload).

Ciò potrebbe essere utile per le filiali al di fuori degli Stati Uniti con una società madre situata all’interno degli Stati Uniti o durante gli accorpamenti quando si consolidano i dati in un unico database Odoo.

Creare il webhook¶

Per creare questo webhook, procedi come segue:

apri l’app Vendite, poi apri Studio e fai clic su Webhook. Il modello Ordine di vendita viene selezionato per impostazione predefinita
fai clic su Nuovo. Il Trigger viene impostato su Su webhook per impostazione predefinita
imposta il Record target su model.env[payload.get('_model')].browse(int(payload.get('_id'))), dove:
- payload.get('_model') recuperà il valore associato con la chiave del model nel payload, ovvero `sale.order`che è il nome tecnico del modello Ordine di vendita
- payload.get('_id') recupera il valore associato alla chiave id nel payload, ad es., il numero di ordini di vendita target nel tuo database Odoo con la S e senza zero iniziale
- int converte l’id recuperato in un intero (ad es., un numero intero) perché il metodo browse() può essere utilizzato solo con un intero.
fai clic su Aggiungi un’azione
nella sezione Tipologia, fai clic su Aggiorna record
Nella sezione Dettagli azione, seleziona Aggiorna, scegli il campo Valuta e poi USD
fai clic su Salva e chiudi.

Testare il webhook¶

Per testare questo webhook, procedi come segue:

una volta aperto Postman, crea una nuova richiesta HTTP e imposta il metodo su POST
copia l’URL del webhook Odoo utilizzando l’icona (link) e incollalo nel campo URL in Postman
Fai clic sulla scheda Corpo e seleziona raw (senza elaborazione).
imposta il tipo di file su JSON, poi copia questo codice, ad es. il payload e incollalo nell’editor del codice:
```
{
    "_model": "sale.order",
    "_id": "SALES ORDER NUMBER"
}
```
nel database Odoo, seleziona un ordine di vendita su cui testare il webhook. Nel codice incollato, sostituisci SALES ORDER NUMBER con il numero dell’ordine di vendita senza la S o eventuali zeri prima del numero. Ad esempio, un ordine di vendita con il numero S00007 deve essere inserito come 7 in Postman
Fai clic su Invia.
consulta il visualizzatore di risposte in Postman per stabilire se il webhook funzioni in maniera appropriata o meno. Se viene restituito un messaggio diverso da 200 OK o status: ok, il numero associato al messaggio aiuta a identificare il problema.

Creare un nuovo contatto¶

Questo webhook utilizza un codice personalizzato per creare un nuovo contatto in un database Odoo quando il sistema esterno invia una richiesta API POST all’URL del webhook che include le informazioni del contatto. Ciò potrebbe essere utile per creare automaticamente nuovi fornitori o clienti.

Creare il webhook¶

Per creare questo webhook, procedi come segue:

apri l’app Contatti, poi apri Studio e fai clic su Webhook. Il modello Contatto viene selezionato per impostazione predefinita
fai clic su Nuovo. Il Trigger viene impostato su Su webhook per impostazione predefinita
imposta il Record target su model.browse([2]). Si tratta essenzialmente di un segnaposto in quanto il codice dell’azione automatizzata dice al webhook cosa è necessario recuperare dal payload e in quale modello è necessario creare il record
fai clic su Aggiungi un’azione
nella sezione Tipologia, fai clic su Esegui codice

copia il codice e incollalo nell’editor nella scheda Codice della sezione Dettagli azione:

# 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'")

fai clic su Salva e chiudi.

Testare il webhook¶

Per testare questo webhook, procedi come segue:

in Postman, crea una nuova richiesta HTTP e imposta il metodo su POST
copia l’URL del webhook Odoo utilizzando l’icona (link) e incollalo nel campo URL in Postman
Fai clic sulla scheda Corpo e seleziona raw (senza elaborazione).

imposta il tipo di file su JSON, poi copia questo codice, ad es. il payload e incollalo nell’editor del codice:

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

nel codice copiato, sostituisci CONTACT NAME, CONTACTEMAIL@EMAIL.COM e CONTACT PHONE NUMBER con le informazioni di un nuovo contatto
Fai clic su Invia.
consulta il visualizzatore di risposte in Postman per stabilire se il webhook funzioni in maniera appropriata o meno. Se viene restituito un messaggio diverso da 200 OK o status: ok, il numero associato al messaggio aiuta a identificare il problema.

Modificare su GitHub