Webhooks¶

Waarschuwing

Het is sterk aanbevolen om te overleggen met een ontwikkelaar, oplossingsarchitect of een andere technische rol bij het beslissen om webhooks te gebruiken en gedurende het implementatieproces. Als ze niet goed zijn geconfigureerd, kunnen webhooks de Odoo-database verstoren en kan het tijd kosten om dit terug te draaien.

Webhooks, die je kunt maken in Odoo Studio, laten je een actie in je Odoo-database automatiseren wanneer een specifieke gebeurtenis plaatsvindt in een ander, extern systeem.

In de praktijk werkt dit als volgt: wanneer de gebeurtenis plaatsvindt in het externe systeem, wordt een databestand (de “payload”) naar de URL van de Odoo-webhook gestuurd via een POST API-verzoek, en wordt een vooraf gedefinieerde actie uitgevoerd in je Odoo-database.

In tegenstelling tot geplande acties, die draaien op vooraf gedefinieerde intervallen, of handmatige API-verzoeken, die expliciet aangeroepen moeten worden, maken webhooks realtime, gebeurtenisgestuurde communicatie en automatisering mogelijk. Je kunt bijvoorbeeld een webhook instellen om je Odoo-voorraadgegevens automatisch bij te laten werken wanneer een verkooporder wordt bevestigd in een extern kassasysteem.

Het instellen van een webhook in Odoo vereist geen code bij het verbinden van twee Odoo-databases, maar het testen van een webhook vereist een extern hulpmiddel. Aangepaste doelrecords of acties kunnen programmeervaardigheden vereisen.

Notitie

Dit artikel behandelt het maken van een webhook die gegevens ontvangt van een externe bron. Het is echter ook mogelijk om een geautomatiseerde actie te maken die gegevens naar een externe webhook stuurt wanneer er een wijziging plaatsvindt in je Odoo-database.

Maak een webhook in Odoo¶

Belangrijk

Test en configureer een webhook in een gedupliceerde database voordat je deze in een live database implementeert, om te zorgen dat de webhook werkt zoals bedoeld.

Tip

Activeer de ontwikkelaarsmodus voordat je een webhook maakt. Dit geeft meer flexibiliteit bij het selecteren van het model waarop de automatiseringsregel zich richt. Het stelt je ook in staat om de technische naam van het model en velden te vinden, wat nodig kan zijn om de payload te configureren.

Om de technische naam van een model te vinden, beweeg je met geactiveerde ontwikkelaarsmodus over de modelnaam en klik je op Interne link. De technische naam staat in het veld Model. Een verkooporderwebhook gebruikt bijvoorbeeld het model Verkooporder, maar de technische naam sale.order wordt gebruikt in de payload.

Ga als volgt te werk om een webhook in Studio te maken:

Open Studio en klik op Webhooks, vervolgens op Nieuw.
Geef de webhook een duidelijke, betekenisvolle naam die het doel aangeeft.
Selecteer indien nodig, en op voorwaarde dat de ontwikkelaarsmodus is geactiveerd, het juiste Model uit het vervolgkeuzemenu. Als de ontwikkelaarsmodus niet is geactiveerd, richt de automatiseringsregel zich standaard op het huidige model.
De URL van de webhook wordt automatisch gegenereerd, maar kan indien nodig worden gewijzigd door op Geheim roteren te klikken. Dit is de URL die moet worden gebruikt bij het implementeren van de webhook in het externe systeem dat updates naar de database stuurt.

Waarschuwing
De URL is vertrouwelijk en moet zorgvuldig worden behandeld. Deel hem niet online of zonder voorzichtigheid, want dat kan onbedoelde toegang tot de Odoo-database verschaffen. Als de URL na de initiële implementatie wordt bijgewerkt, zorg er dan voor dat je hem ook bijwerkt in het externe systeem.
Schakel indien gewenst Logboek van aanroepen in om de geschiedenis van API-verzoeken naar de URL van de webhook bij te houden, bv. voor probleemoplossing.
Als het systeem dat de webhook verstuurt niet Odoo is, pas dan de code van Doelrecord aan om te zoeken naar het JSON-record dat in de payload zit wanneer het API-verzoek naar de URL van de webhook wordt gedaan. Als het systeem dat de webhook verstuurt een Odoo-database is, zorg er dan voor dat id en model in de payload voorkomen.

Als de webhook wordt gebruikt om records in de Odoo-database te maken, gebruik dan model.browse(i) of model.search(i) in plaats van het standaard Doelrecord-formaat.
Klik op Voeg een actie toe in het tabblad Uit te voeren acties om de acties te definiëren die moeten worden uitgevoerd.
Voordat je de webhook in het externe systeem implementeert, test hem om te controleren of hij werkt zoals bedoeld.

Tip

Webhooks kunnen ook worden gemaakt via het menu Automatisering in Studio door de activatie Bij webhook te selecteren.
Klik op de smartknop Logs bovenaan het formulier Automatiseringsregels om de geschiedenis van API-verzoeken te bekijken als Oproepen loggen is ingeschakeld.
Als het doel van de webhook iets anders is dan het bijwerken van een bestaand record, bv. het aanmaken van een nieuw record, moet de actie Code uitvoeren worden gekozen.

Een webhook testen¶

Het testen van een webhook vereist een testpayload en een externe tool of systeem, zoals Postman, om de payload te verzenden via een POST API-verzoek. Deze sectie presenteert de stappen om een webhook te testen in Postman.

Tip

Zie de sectie met webhook use cases voor stapsgewijze uitleg over het testen van webhooks met testpayloads.
Neem contact op met hun supportteam voor specifieke hulp bij het testen van een webhook met Postman.

Maak in Postman een nieuw HTTP-verzoek en stel de methode in op POST.
Kopieer de URL van de webhook uit je Odoo-database met het (link)-icoon en plak deze in het URL-veld in Postman.
Klik op het tabblad Body en selecteer raw.
Stel het bestandstype in op JSON, kopieer vervolgens de code uit de testpayload en plak deze in de code-editor.
Klik op Verzenden.

In de Response-viewer onderaan het scherm in Postman geven details, waaronder een HTTP-responscode, aan of de webhook correct functioneert.

Een 200 OK of status: ok bericht geeft aan dat de webhook goed functioneert aan de kant van Odoo. Vanaf hier kan de implementatie beginnen met het andere systeem om automatisch de API-verzoeken naar de URL van de Odoo webhook te sturen.
Als een andere respons wordt geretourneerd, helpt het bijbehorende nummer om het probleem te identificeren. Bijvoorbeeld, een 500 Internal Server Error bericht betekent dat Odoo de oproep niet correct kon interpreteren. Controleer in dit geval of de velden in het JSON-bestand correct zijn gekoppeld in de configuratie van de webhook en in het systeem dat de testoproep verstuurt.

Tip

Het inschakelen van oproeplogboeken in de configuratie van de webhook in Odoo biedt foutenlogboeken als de webhook niet functioneert zoals bedoeld.

Een webhook implementeren in een extern systeem¶

Wanneer de webhook succesvol is gemaakt in Odoo en getest, implementeer deze dan in het systeem dat gegevens naar de Odoo-database stuurt, en zorg ervoor dat de POST API-verzoeken naar de URL van de webhook worden gestuurd.

Gebruiksscenario’s voor webhooks¶

Hieronder staan twee voorbeelden van hoe je webhooks in Odoo kunt gebruiken. Voor elk voorbeeld wordt een testpayload gegeven, die te vinden is in de sectie over het testen van de webhook. Postman wordt gebruikt om de testpayload te verzenden.

Valuta van een verkooporder bijwerken¶

Deze webhook werkt een verkooporder in de Verkoop-app bij naar USD wanneer het externe systeem een POST API-verzoek naar de URL van de webhook stuurt dat het verkoopordernummer bevat (dat wordt geïdentificeerd door het id-record van de payload).

Dit kan nuttig zijn voor dochterondernemingen buiten de Verenigde Staten met een moederbedrijf gevestigd binnen de Verenigde Staten of tijdens fusies bij het samenvoegen van gegevens in één Odoo-database.

Webhook aanmaken¶

Volg deze stappen om de webhook aan te maken:

Open de Verkoop-app, open Studio en klik op Webhooks. Het model Verkooporder is standaard geselecteerd.
Klik op Nieuw. De Trigger staat standaard ingesteld op Bij webhook.
Stel het Doelrecord in op model.env[payload.get('_model')].browse(int(payload.get('_id'))), waarbij:
- payload.get('_model') de waarde ophaalt die is gekoppeld aan de model-sleutel in de payload, namelijk sale.order, de technische naam van het model Verkooporder.
- payload.get('_id') de waarde ophaalt die is gekoppeld aan de id-sleutel in de payload, namelijk het nummer van de doelverkooporder in je Odoo-database zonder de S en voorloopnullen.
- int converteert het opgehaalde id naar een geheel getal omdat de methode browse() alleen met een geheel getal kan worden gebruikt.
Klik op Actie toevoegen.
Klik in de sectie Type op Record bijwerken.
Selecteer in de sectie Actiedetails Bijwerken, kies het veld Valuta en selecteer USD.
Klik op Opslaan en sluiten.

Webhook testen¶

Volg deze stappen om de webhook te testen:

Open Postman en maak een nieuw HTTP-verzoek aan met de methode ingesteld op POST.
Kopieer de URL van de Odoo-webhook met het (link)-icoon en plak deze in het URL-veld in Postman.
Klik op het tabblad Body en selecteer raw.
Stel het bestandstype in op JSON, kopieer vervolgens deze code (de payload) en plak deze in de code-editor:
```
{
    "_model": "sale.order",
    "_id": "SALES ORDER NUMBER"
}
```
Kies in je Odoo-database een verkooporder om de webhook op te testen. Vervang in de geplakte code SALES ORDER NUMBER door het nummer van de verkooporder zonder de S en eventuele nullen voor het nummer. Een verkooporder met nummer S00007 moet bijvoorbeeld worden ingevoerd als 7 in Postman.
Klik op Verzenden.
Raadpleeg de antwoordviewer in Postman om te bepalen of de webhook goed functioneert. Als een ander bericht dan 200 OK of status: ok wordt geretourneerd, helpt het nummer bij het bericht om het probleem te identificeren.

Maak een nieuw contact aan¶

Deze webhook gebruikt aangepaste code om een nieuw contact aan te maken in een Odoo-database wanneer het externe systeem een POST API-verzoek naar de URL van de webhook stuurt met de contactinformatie. Dit kan handig zijn om automatisch nieuwe leveranciers of klanten aan te maken.

Webhook aanmaken¶

Volg deze stappen om de webhook aan te maken:

Open de app Contacten, open Studio en klik op Webhooks. Het model Contactpersoon is standaard geselecteerd.
Klik op Nieuw. De Trigger staat standaard ingesteld op Bij webhook.
Stel het Doelrecord in op model.browse([2]). Dit is in feite een placeholder, omdat de code in de geautomatiseerde actie de webhook vertelt wat uit de payload moet worden opgehaald en in welk model het record moet worden aangemaakt.
Klik op Actie toevoegen.
Klik in de sectie Type op Code uitvoeren.

Kopieer deze code en plak deze in de code-editor op het tabblad Code van de sectie Actiedetails:

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

Klik op Opslaan en sluiten.

Webhook testen¶

Volg deze stappen om de webhook te testen:

Maak in Postman een nieuw HTTP-verzoek aan en stel de methode in op POST.
Kopieer de URL van de Odoo-webhook met het (link)-icoon en plak deze in het URL-veld in Postman.
Klik op het tabblad Body en selecteer raw.

Stel het bestandstype in op JSON, kopieer vervolgens deze code (de payload) en plak deze in de code-editor:

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

Vervang in de geplakte code de CONTACT NAME, CONTACTEMAIL@EMAIL.COM en CONTACT PHONE NUMBER door de gegevens van een nieuw contactpersoon.
Klik op Verzenden.
Raadpleeg de antwoordviewer in Postman om te bepalen of de webhook goed functioneert. Als een ander bericht dan 200 OK of status: ok wordt geretourneerd, helpt het nummer bij het bericht om het probleem te identificeren.

Bewerken op GitHub