Webhooks¶

Advertencia

Se recomienda encarecidamente consultar con un desarrollador, un arquitecto de soluciones u otro perfil técnico al decidir utilizar webhooks y durante todo el proceso de implementación. Si no se configuran correctamente, los webhooks pueden alterar la base de datos de Odoo y su reversión puede llevar tiempo.

Los webhooks, que son reglas de automatización con el desencadenante Al recibir un webhook, le permiten automatizar una acción en su base de datos de Odoo cuando se produce un evento específico en otro sistema externo.

En la práctica, esto funciona de la siguiente manera: cuando se produce el evento en el sistema externo, se envía un archivo de datos (el «payload») a la URL del webhook de Odoo mediante una solicitud de API POST, y se ejecuta una acción predefinida en su base de datos de Odoo.

A diferencia de las acciones planificadas, que se ejecutan en intervalos predefinidos, o de las solicitudes de API manuales, que deben invocarse explícitamente, los webhooks permiten una comunicación y una automatización en tiempo real basadas en eventos. Por ejemplo, puede configurar un webhook para que los datos de inventario de Odoo se actualicen automáticamente cuando se confirme un pedido de venta en un sistema de punto de venta externo.

Configurar un webhook en Odoo no requiere programación cuando se conectan dos bases de datos de Odoo, pero probar un webhook requiere una herramienta externa. Los registros o acciones de destino personalizados pueden requerir conocimientos de programación.

Nota

Este artículo trata sobre la creación de un webhook que recibe datos de una fuente externa. Sin embargo, también es posible crear una acción automatizada que envíe datos a un webhook externo cuando se produzca un cambio en su base de datos de Odoo.

Crear un webhook en Odoo¶

Importante

Antes de implementar un webhook en una base de datos en producción, configúrelo y pruébelo utilizando una base de datos duplicada (de prueba) para asegurarse de que funciona según lo previsto.

Truco

Activar el modo de desarrollador antes de crear un webhook proporciona mayor flexibilidad a la hora de seleccionar el modelo al que se dirige la regla de automatización. También le permite encontrar el nombre técnico del modelo y de los campos, lo cual puede ser necesario para configurar el payload.

Para encontrar el nombre técnico de un modelo, con el modo de desarrollador activado, pase el cursor sobre el nombre del modelo y haga clic en (Enlace interno). El nombre técnico se encuentra en el campo Modelo. Por ejemplo, un webhook de pedido de venta utiliza el modelo Pedido de venta, pero en el payload se utiliza el nombre técnico sale.order.

Para crear un webhook, siga estos pasos:

Con el modo desarrollador activado, vaya a Ajustes ‣ Técnico ‣ Automatización ‣ Reglas de automatización y haga clic en Nuevo.
Asigne al webhook un nombre claro y significativo que identifique su finalidad.
Seleccione el Modelo adecuado en la lista desplegable.
Establezca el Desencadenante en Al recibir un webhook.
La URL del webhook se genera automáticamente, pero se puede cambiar si es necesario haciendo clic en Rotar secreto. Esta es la URL que debe utilizarse al implementar el webhook en el sistema externo que enviará las actualizaciones a la base de datos.

Advertencia
La URL es confidencial y debe tratarse con cuidado. Compartirla en línea o sin precaución puede otorgar un acceso no deseado a la base de datos de Odoo. Si la URL se actualiza después de la implementación inicial, asegúrese de actualizarla también en el sistema externo.
Si lo desea, active Registrar llamadas para llevar un historial de las solicitudes de API realizadas a la URL del webhook, por ejemplo, con fines de resolución de problemas.
Si el sistema que envía el webhook no es Odoo, ajuste el código de Registro de destino para buscar el registro JSON incluido en el payload cuando se realice la solicitud de API a la URL del webhook. Si el sistema que envía el webhook es una base de datos de Odoo, asegúrese de que id y model aparezcan en el payload.

Si el webhook se utiliza para crear registros en la base de datos de Odoo, utilice model.browse(i) o model.search(i) en lugar del formato predeterminado de Registro de destino.
Haga clic en Añadir una acción en la pestaña Acciones a realizar para definir las acciones que se ejecutarán.
Antes de implementar el webhook en el sistema externo, pruébelo para asegurarse de que funciona según lo previsto.

Truco

Para acceder al historial de solicitudes de API si se ha activado Registrar llamadas, haga clic en el botón inteligente Registros situado en la parte superior del formulario de Reglas de automatización.
Si la finalidad del webhook es distinta de actualizar un registro existente, por ejemplo, crear un nuevo registro, debe elegirse la acción Ejecutar código.

Probar un webhook¶

Para probar un webhook se necesita un payload de prueba y una herramienta o sistema externo, como Postman, para enviar el payload mediante una solicitud de API POST. Esta sección presenta los pasos para probar un webhook en Postman.

Truco

Consulte la sección de casos de uso de webhooks para obtener explicaciones paso a paso sobre cómo probar webhooks utilizando payloads de prueba.
Para obtener ayuda específica sobre cómo probar un webhook con Postman, póngase en contacto con su equipo de soporte.

En Postman, cree una nueva solicitud HTTP y configure su método como POST.
Copie la URL del webhook desde su base de datos de Odoo mediante el icono (enlace) y péguela en el campo de URL de Postman.
Haga clic en la pestaña Body y seleccione raw.
Establezca el tipo de archivo en JSON, luego copie el código del payload de prueba y péguelo en el editor de código.
Haga clic en Send.

En el visor Response de la parte inferior de la pantalla en Postman, los detalles, incluido un código de respuesta HTTP, indican si el webhook funciona correctamente o no.

Un mensaje 200 OK o status: ok indica que el webhook funciona correctamente en el lado de Odoo. A partir de aquí, se puede comenzar la implementación con el otro sistema para enviar automáticamente las solicitudes de API a la URL del webhook de Odoo.
Si se devuelve cualquier otra respuesta, el número asociado a ella ayuda a identificar el problema. Por ejemplo, un mensaje 500 Internal Server Error significa que Odoo no pudo interpretar correctamente la llamada. En este caso, asegúrese de que los campos que se encuentran en el archivo JSON estén correctamente asignados en la configuración del webhook y en el sistema que envía la llamada de prueba.

Truco

Activar el registro de llamadas en la configuración del webhook en Odoo proporciona registros de error si el webhook no funciona según lo previsto.

Implementar un webhook en un sistema externo¶

Una vez creado y probado correctamente el webhook en Odoo, impleméntelo en el sistema que envía datos a la base de datos de Odoo, asegurándose de que las solicitudes de API POST se envíen a la URL del webhook.

Casos de uso de webhooks¶

A continuación se presentan dos ejemplos de cómo utilizar webhooks en Odoo. Para cada ejemplo se proporciona un payload de prueba, que se puede encontrar en la sección sobre cómo probar el webhook. Postman se utiliza para enviar el payload de prueba.

Actualizar la divisa de un pedido de venta¶

Este webhook actualiza un pedido de venta en la aplicación Ventas a USD cuando el sistema externo envía una solicitud de API POST a la URL del webhook que incluye el número de ese pedido de venta (identificado por el registro id del payload).

Esto puede ser útil para filiales fuera de Estados Unidos con una empresa matriz ubicada dentro de Estados Unidos, o durante fusiones al consolidar datos en una única base de datos de Odoo.

Crear el webhook¶

Para crear este webhook, siga estos pasos:

Vaya a Ajustes ‣ Técnico ‣ Automatización ‣ Reglas de automatización y haga clic en Nuevo. Seleccione el modelo Pedido de venta y establezca el Desencadenante en Al recibir un webhook.
Establezca el Registro de destino en model.env[payload.get('model')].browse(int(payload.get('id'))), donde:
- payload.get('model') recupera el valor asociado a la clave model en el payload, es decir, sale.order, que es el nombre técnico del modelo Pedido de venta.
- payload.get('id') recupera el valor asociado a la clave id en el payload, es decir, el número del pedido de venta de destino en su base de datos de Odoo, sin la S ni los ceros iniciales.
- int convierte el id recuperado en un número entero, ya que el método browse() solo puede utilizarse con un número entero.
Haga clic en Añadir una acción.
En la sección Tipo, haga clic en Actualizar registro.
En la sección Detalles de la acción, seleccione Actualizar, elija el campo Divisa y seleccione USD.
Haga clic en Guardar y cerrar.

Probar el webhook¶

Para probar este webhook, siga estos pasos:

Con Postman abierto, cree una nueva solicitud HTTP y configure su método como POST.
Copie la URL del webhook de Odoo mediante el icono (enlace) y péguela en el campo de URL de Postman.
Haga clic en la pestaña Body y seleccione raw.
Establezca el tipo de archivo en JSON, luego copie este código, es decir, el payload, y péguelo en el editor de código:
```
{
    "model": "sale.order",
    "id": "SALES ORDER NUMBER"
}
```
En su base de datos de Odoo, elija un pedido de venta para probar el webhook. En el código pegado, sustituya SALES ORDER NUMBER por el número del pedido de venta sin la S ni los ceros que lo preceden. Por ejemplo, un pedido de venta con el número S00007 debe introducirse como 7 en Postman.
Haga clic en Send.
Consulte el visor de respuestas en Postman para determinar si el webhook funciona correctamente o no. Si se devuelve un mensaje distinto de 200 OK o status: ok, el número asociado al mensaje ayuda a identificar el problema.

Crear un nuevo contacto¶

Este webhook utiliza código personalizado para crear un nuevo contacto en una base de datos de Odoo cuando el sistema externo envía una solicitud de API POST a la URL del webhook que incluye la información del contacto. Esto puede ser útil para crear automáticamente nuevos proveedores o clientes.

Crear el webhook¶

Para crear este webhook, siga estos pasos:

Vaya a Ajustes ‣ Técnico ‣ Automatización ‣ Reglas de automatización y haga clic en Nuevo. Seleccione el modelo Contacto y establezca el Desencadenante en Al recibir un webhook.
Establezca el Registro de destino en model.browse([2]). Esto es esencialmente un marcador de posición, ya que el código de la acción automatizada indica al webhook qué debe recuperarse del payload y en qué modelo debe crearse el registro.
Haga clic en Añadir una acción.
En la sección Tipo, haga clic en Ejecutar código.

Copie este código y péguelo en el editor de código de la pestaña Código de la sección Detalles de la acción:

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

Haga clic en Guardar y cerrar.

Probar el webhook¶

Para probar este webhook, siga estos pasos:

En Postman, cree una nueva solicitud HTTP y configure su método como POST.
Copie la URL del webhook de Odoo mediante el icono (enlace) y péguela en el campo de URL de Postman.
Haga clic en la pestaña Body y seleccione raw.

Establezca el tipo de archivo en JSON, luego copie este código, es decir, el payload, y péguelo en el editor de código:

{
    "name": "CONTACT NAME",
    "email": "[email protected]",
    "phone": "CONTACT PHONE NUMBER"
}

En el código pegado, sustituya CONTACT NAME, [email protected] y CONTACT PHONE NUMBER por la información de un nuevo contacto.
Haga clic en Send.
Consulte el visor de respuestas en Postman para determinar si el webhook funciona correctamente o no. Si se devuelve un mensaje distinto de 200 OK o status: ok, el número asociado al mensaje ayuda a identificar el problema.