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.

Los webhooks, que se pueden crear en Odoo Studio, te permiten automatizar una acción en tu base de datos de Odoo cuando ocurre un evento específico en otro sistema externo.

En la práctica, esto funciona de la siguiente manera: cuando ocurre 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 API POST, y se ejecuta una acción predefinida en tu base de datos de Odoo.

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

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 habilidades de programación.

Nota

Este artículo cubre 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 ocurre un cambio en tu base de datos de Odoo.

Crea un webhook en Odoo¶

Importante

Antes de implementar un webhook en una base de datos en producción, configúralo y pruébalo usando una base de datos duplicada para asegurar que el webhook funcione según lo previsto.

Truco

Activar el modo de desarrollador antes de crear un webhook proporciona mayor flexibilidad al seleccionar el modelo al que apunta la regla de automatización. También te permite encontrar el nombre técnico del modelo y los campos, que pueden ser necesarios para configurar el payload.

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

Para crear un webhook en Studio, procede de la siguiente manera:

Abre Studio y haz clic en Webhooks, luego en Nuevo.
Dale al webhook un nombre claro y significativo que identifique su propósito.
Si es necesario y siempre que el modo de desarrollador esté activado, selecciona el Modelo apropiado del menú desplegable. Si el modo de desarrollador no está activado, la regla de automatización apunta al modelo actual de forma predeterminada.
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 usarse al implementar el webhook en el sistema externo que enviará 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 proporcionar acceso no deseado a la base de datos de Odoo. Si la URL se actualiza después de la implementación inicial, asegúrate de actualizarla en el sistema externo.
Si lo deseas, habilita Registrar llamadas para rastrear el historial de solicitudes API realizadas a la URL del webhook, por ejemplo, para fines de solución de problemas.
Si el sistema que envía el webhook no es Odoo, ajusta el código de Registro de destino para buscar el registro JSON incluido en el payload cuando se realiza la solicitud API a la URL del webhook. Si el sistema que envía el webhook es una base de datos de Odoo, asegúrate de que el id y el model aparezcan en el payload.

Si el webhook se usa para crear registros en la base de datos de Odoo, usa model.browse(i) o model.search(i) en lugar del formato predeterminado de Registro de destino.
Haz clic en Añadir una acción en la pestaña Acciones pendientes para definir las acciones que se ejecutarán.
Antes de implementar el webhook en el sistema externo, pruébalo para asegurarte de que funciona como se espera.

Truco

Los webhooks también se pueden crear a través del menú Automatizaciones en Studio seleccionando el disparador En webhook.
Para acceder al historial de solicitudes de API si se ha habilitado Registrar llamadas, haz clic en el botón inteligente Registros en la parte superior del formulario Reglas de automatización.
Si el propósito del webhook es algo distinto de actualizar un registro existente, por ejemplo, crear un registro nuevo, se debe elegir la acción Ejecutar código.

Probar un webhook¶

Probar un webhook requiere una carga útil de prueba y una herramienta o sistema externo, como Postman, para enviar la carga útil mediante una solicitud de API POST. Esta sección presenta los pasos para probar un webhook en Postman.

Truco

Consulta la sección de casos de uso de webhooks para obtener explicaciones paso a paso sobre cómo probar webhooks utilizando cargas útiles de prueba.
Para obtener ayuda específica con la prueba de un webhook con Postman, contacta con su equipo de soporte.

En Postman, crea una nueva solicitud HTTP y establece su método en POST.
Copia la URL del webhook de tu base de datos de Odoo usando el icono (enlace) y pégala en el campo URL de Postman.
Haz clic en la pestaña Cuerpo y selecciona sin procesar.
Establece el tipo de archivo en JSON, luego copia el código de la carga útil de prueba y pégalo en el editor de código.
Haz clic en Enviar.

En el visor Respuesta en la parte inferior de la pantalla de 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 del lado de Odoo. Desde 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 ayuda a identificar el problema. Por ejemplo, un mensaje 500 Internal Server Error significa que Odoo no pudo interpretar la llamada correctamente. En este caso, asegúrate de que los campos del archivo JSON estén correctamente mapeados 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 errores si el webhook no funciona como se espera.

Implementar un webhook en un sistema externo¶

Cuando el webhook se haya creado correctamente en Odoo y se haya probado, impleméntalo en el sistema que envía datos a la base de datos de Odoo, asegurándote de que las solicitudes de API POST se envíen a la URL del webhook.

Casos de uso de webhook¶

A continuación se muestran dos ejemplos de cómo usar webhooks en Odoo. Se proporciona una carga útil de prueba para cada ejemplo, y se puede encontrar en la sección sobre prueba del webhook. Se usa Postman para enviar la carga útil de prueba.

Actualizar la moneda 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 ese número de pedido de venta (identificado por el registro id de la carga útil).

Esto podría ser útil para subsidiarias fuera de Estados Unidos con una empresa matriz ubicada dentro de Estados Unidos o durante fusiones al consolidar datos en una base de datos de Odoo.

Crear el webhook¶

Para crear este webhook, procede de la siguiente manera:

Abre la aplicación Ventas, luego abre Studio y haz clic en Webhooks. El modelo Pedido de venta está seleccionado por defecto.
Haz clic en Nuevo. El Disparador está configurado en En webhook por defecto.
Set the Target Record to model.env[payload.get('model')].browse(int(payload.get('id'))), where:
- payload.get('model') retrieves the value associated with the model key in the payload, i.e., sale.order, which is the technical name of the Sales Order model.
- payload.get('id') retrieves the value associated with the id key in the payload, i.e., the number of the target sales order in your Odoo database with the S and leading zeros removed.
- int convierte el id recuperado en un entero (es decir, un número entero) porque el método browse() solo se puede usar con un entero.
Haz clic en Añadir una acción.
En la sección Tipo, haz clic en Actualizar registro.
En la sección Detalles de la acción, selecciona Actualizar, elige el campo Moneda y selecciona USD.
Haz clic en Guardar y cerrar.

Probar el webhook¶

Para probar este webhook, procede de la siguiente manera:

Con Postman abierto, crea una nueva solicitud HTTP y configura su método como POST.
Copia la URL del webhook de Odoo usando el icono (enlace) y pégala en el campo URL en Postman.
Haz clic en la pestaña Cuerpo y selecciona sin procesar.
Configura el tipo de archivo como JSON, luego copia este código, es decir, la carga útil, y pégalo en el editor de código:
```
{
    "model": "sale.order",
    "id": "SALES ORDER NUMBER"
}
```
En tu base de datos de Odoo, elige un pedido de venta para probar el webhook. En el código pegado, reemplaza SALES ORDER NUMBER con el número del pedido de venta sin la S ni los ceros antes del número. Por ejemplo, un pedido de venta con el número S00007 debe ingresarse como 7 en Postman.
Haz clic en Enviar.
Consulta 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 con el 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 API POST a la URL del webhook que incluye la información del contacto. Esto podría ser útil para crear automáticamente nuevos proveedores o clientes.

Crear el webhook¶

Para crear este webhook, procede de la siguiente manera:

Abre la aplicación Contactos, luego abre Studio y haz clic en Webhooks. El modelo Contacto está seleccionado por defecto.
Haz clic en Nuevo. El Disparador está configurado en En webhook por defecto.
Establece el Registro de destino en model.browse([2]). Esto es esencialmente un marcador de posición, ya que el código en la acción automatizada le indica al webhook qué debe recuperarse de la carga útil y en qué modelo debe crearse el registro.
Haz clic en Añadir una acción.
En la sección Tipo, haz clic en Ejecutar código.

Copia este código y pégalo en el editor de código en 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'")

Haz clic en Guardar y cerrar.

Probar el webhook¶

Para probar este webhook, procede de la siguiente manera:

En Postman, crea una nueva solicitud HTTP y establece su método en POST.
Copia la URL del webhook de Odoo usando el icono (enlace) y pégala en el campo URL en Postman.
Haz clic en la pestaña Cuerpo y selecciona sin procesar.

Configura el tipo de archivo como JSON, luego copia este código, es decir, la carga útil, y pégalo en el editor de código:

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

En el código pegado, reemplaza CONTACT NAME, CONTACTEMAIL@EMAIL.COM y CONTACT PHONE NUMBER con la información de un nuevo contacto.
Haz clic en Enviar.
Consulta 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 con el mensaje ayuda a identificar el problema.

Editar en GitHub