Webhooks¶

Advertencia

Le recomendamos consultar a un desarrollador, arquitecto de soluciones o cualquier otra persona con experiencia técnica antes de decidir si usar webhooks y durante el proceso de implementación. Si no se hace una configuración adecuada, los webhooks pueden afectar la base de datos de Odoo y puede tomar tiempo solucionar estos problemas.

Webhooks, which can be created in Studio, are automation rules triggered by external events via user-defined HTTP callbacks. When an external system sends data to an Odoo webhook’s URL (the «trigger») with a data file (the «payload»), Odoo responds with a predefined action in the database.

Unlike scheduled actions or manual API calls, webhooks enable real-time communication and automation. For example, if a sales order is confirmed in an external POS system, a webhook can instantly update Odoo’s inventory, ensuring system synchronization.

Nota

This article covers creating a webhook that takes in data from an external source. However, an automated action that sends an API call to an external webhook can also be created.

Crear un webhook en Studio¶

Los webhooks se configuran en Studio y esta configuración se divide entre su activador y sus acciones.

Truco

Para configurar un webhook en Odoo, no es necesario escribir o entender código al conectarse con bases de datos de Odoo, pero realizar pruebas requiere una herramienta externa como Postman. Es posible que sí necesite escribir o entender código para los registros objetivo o las acciones personalizadas.
Active el modo de desarrollador para modificar el modelo objetivo del webhook (como pedidos de venta o información de contacto) y para saber cuál es el nombre técnico del modelo (que puede necesitar para una configuración adecuada de la carga útil).

Configurar el activador del webhook¶

Para crear un webhook con Studio abra Studio, haga clic en Webhooks y después en Nuevo. Aquí puede nombrar al webhook, modificar su modelo (el tipo de entrada de información en la base de datos que será el objetivo) si es necesario, y activar si las llamadas que se hagan a la URL del webhook se deben registrar (para rastrear el historial de llamadas del webhook para resolución de problemas).

La URL del webhook se genera automáticamente. Esta es la URL que se debe usar para realizar pruebas del webhook y para conectarlo al sistema externo que enviará las actualizaciones a la base de datos.

Peligro

La URL del webhook es confidencial y debe tratarse con cuidado. Si se comparte en línea o sin precaución podría dar acceso a agentes no deseados en la base de datos de Odoo. Haga clic en Rotar secreto si necesita cambiar la URL.

Finally, if the system sending the webhook is not Odoo, adjust the Target Record actions to look for the JSON record that is included in the API call’s payload when the call is made to the webhook’s URL. If the system sending the webhook is an Odoo database, then make sure that the id and model appear in the payload.

Truco

Although the Model is set in Odoo, it is the model’s technical name that must be included in the payload. Hover over the model name, then click the (Internal link) icon to find this technical name in the Model field. For example, a sales order webhook uses the Sales Order model, but the technical name sale.order is used in the payload.

Nota

When creating a record in the Odoo database, the target record’s default format should not be used. Instead, use model.browse(i) or model.search(i).

Set the webhook’s action¶

To set a webhook’s action while configuring a webhook, click Add an action under the Actions To Do tab. Click the action’s Type and set the fields as needed.

Probar el webhook¶

Nota

Testing the webhook requires the webhook to be set up, a test payload to send to the webhook, and an external tool or system to send the payload through a POST API request. Consider using a tool like Postman so less technical skills are required.

If a message saying 200 OK or status: ok gets returned during testing, then the webhook is functioning properly on Odoo’s side. From here, implementation can begin with the other tool to automatically send those webhook calls into Odoo using the webhook’s URL.

If any other responses are returned, the number sent in the response helps to identify the problem. For example, a 500 Internal Server Error means that Odoo could not interpret the call properly. If this gets returned, ensure the fields found in the JSON file are properly mapped in the webhook’s configuration and in the system sending the test call. Turning on call logging in the webhook’s configuration provides error logs if the webhook is not functioning as intended.

Implement the webhook¶

Once the webhook is fully configured, begin connecting it to the system that sends data to the Odoo database through this webhook. Make sure that the API calls are sent to the webhook’s URL when setting that system up.

Webhook use cases¶

Below are two examples of how to use webhooks in Odoo. These webhooks require external tools (which are listed with the example).

Advertencia

Consult with a developer, solution architect, or another technical role when deciding to implement webhooks. If not properly configured, webhooks may disrupt the Odoo database and can take time to revert.

Update a sales order’s currency¶

This webhook updates a sales order in the Sales app to USD. It useful for subsidiaries outside the United States with a mother company located inside the United States or during mergers when consolidating data into one Odoo database.

Configurar el activador del webhook¶

To set up this webhook, open the Sales app. Then, set the trigger so the Model is set to Sales Order. Also, set the Target Record to model.env[payload.get('model')].browse(int(payload.get('id'))). This is broken down below.

model: what gets updated in Odoo (in this case, sales orders). This matches the Model set earlier.
env: where the action takes place. In this case, it is Odoo.
payload: what is sent to the webhook’s URL. This contains the information that updates the sales order.
get(“model”): tells the webhook what database record to look at. In this case, the webhook retrieves (get) the data tied to a specific model. In this example, this is the Sales Order model.
browse: tells the webhook to look in the model (Sales Order) set by the payload for what to update.
int: turns the target into an integer (a whole number). This is important in case some words (a string) or a decimal number is included in the payload’s target record.
get(“id”): identifies the sales order number that is being updated in Odoo.

Set the webhook’s action¶

After setting the trigger, set the webhook’s action by clicking Add an action. For the Type, click Update Record. Then, select Update, choose the field Currency, and select USD to have the currency field updated to USD. Finally, click Save & Close.

Webhook setup summary¶

To summarize what is set up, the webhook targets sales orders, identified by their sales order number, and updates their currency to USD when a POST request is sent to the webhook’s URL that includes that sales order number (which is identified by the payload’s id record).

Probar el webhook¶

Test the webhook’s setup to make sure everything is correct. This process uses a tool called Postman to send the simulated trigger.

This section walks through the steps to test this webhook in Postman, but does not offer help if there’s an issue within that tool. To get specific help with Postman, contact their support team.

Once Postman is open, create a new HTTP request and set its method to POST. Next, copy the webhook’s URL that is being tested and paste it into the URL field in Postman. After that, click the Body tab and select the raw option. Set the file type to JSON, then copy this code and paste it into the file.

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

From here, choose a sales order to test the webhook on. If it is not possible to test in a live Odoo database, consider creating a demo database with a sample sales order and the webhook that was configured. Replace SALES ORDER NUMBER with the sales order’s number without the S or any zeros before the number. For example, a sales order with the number S00007 should be entered as 7 in Postman. Finally, click Send in Postman.

If a message saying 200 OK or status: ok gets returned, then the webhook is functioning properly on Odoo’s side. The test sales order’s currency is updated. From here, implementation can begin with the other tool to automatically send those webhook calls into Odoo using the webhook’s URL.

If any other responses are returned, the number associated with them helps to identify the problem. For example, a 500 Internal Server Error means that Odoo could not interpret the call properly. If this gets returned, ensure the model and id fields are properly mapped in the webhook’s configuration and in Postman.

Crear un nuevo contacto¶

This webhook uses custom code to create a new contact in an Odoo database. This could be helpful for automatically creating new vendors or customers.

Configurar el activador del webhook¶

To set up this webhook, open the Contacts app. Then, set the trigger so the Model is set to Contact. Also, set the Target Record to model.browse([2]). This is broken down below.

model: what gets updated in Odoo (in this case, a contact). This matches the Model set earlier.
browse: tells the webhook to look in the model (the contacts) set by the payload for what to create.

Set the webhook’s action¶

After setting the trigger, set the webhook’s action by clicking Add an action. For the Type, click Execute Code, then set the code to the sample code below. Finally, click Save & Close.

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

Webhook setup summary¶

To summarize what is set up, the webhook creates a contact when an API call is sent to the webhook’s URL that includes the contact’s information.

Probar el webhook¶

Test the webhook’s setup to make sure everything is correct. This process uses a tool called Postman to send the simulated trigger.

This section walks through the steps to test this webhook in Postman, but does not offer help if there’s an issue within that tool. To get specific help with Postman, contact their support team.

Once Postman is open, create a new request, and set its method to POST. Next, copy the webhook’s URL that is being tested and paste it into the URL field in Postman. After that, click the Body tab and click raw. Set the file type to JSON, then copy this code and paste it into the file.

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

Replace the fields above with a new contact’s information in Postman, and then click Send.

If a message saying 200 OK or status: ok gets returned, then the webhook is functioning properly on Odoo’s side. The new test contact appears in the Contacts app. From here, implementation can begin with the other tool to automatically send those webhook calls into Odoo using the webhook’s URL.

If any other responses are returned, the number associated with them helps to identify the problem. For example, a 500 Internal Server Error means that Odoo could not interpret the call properly. If this gets returned, ensure the fields found in the JSON file are properly mapped in the webhook’s configuration and in Postman.

Edit on GitHub