Webhooks

警告

*强烈建议*在决定使用网络钩子和整个实施过程中咨询开发人员、解决方案架构师或其他技术人员。如果配置不当，网络钩子可能会扰乱 Odoo 数据库，并可能需要一段时间才能恢复。

Webhooks, which can be created in Odoo Studio, allow you to automate an action in your Odoo database when a specific event occurs in another, external system.

In practice, this works as follows: when the event occurs in the external system, a data file (the “payload”) is sent to the Odoo webhook’s URL via a POST API request, and a predefined action is performed in your Odoo database.

与在预定时间间隔内运行的预定操作或需要明确调用的手动 API 请求不同，网络钩子可实现实时、事件驱动的通信和自动化。例如，当外部销售点系统确认销售订单时，您可以设置一个网络钩子来自动更新您的 Odoo 库存数据。

当连接两个 Odoo 数据库时，在 Odoo 中设置网络钩子无需编码，但 测试网络钩子 需要外部工具。 自定义目标记录或操作 可能需要编程技能。

注解

本文涉及创建一个可从外部来源*接收*数据的网络钩子。然而，也可以创建一个自动操作，当 Odoo 数据库发生变化时，该操作 向外部网络钩子 发送数据。

在 Odoo 中创建网络钩子

重要

在实时数据库中实施网络钩子之前，请使用 重复数据库 对其进行配置和测试，以确保网络钩子按预期运行。

小技巧

:ref:` 在创建网络钩子之前激活开发者模式 <developer-mode>`，可以更灵活地选择 自动化规则的目标模型。它还支持您找到模型和字段的技术名称，这可能是配置有效载荷所需要的。

要查找模型的技术名称，请在激活开发者模式后将鼠标悬停在模型名称上，然后点击 （内部链接）。技术名称可在 模型 字段中找到。例如，销售订单网络钩子使用 销售订单 模型，但在有效载荷中使用了技术名称 sale.order。

在**Studio**中创建网络钩子的步骤如下：

  1. 打开 Studio 并点击 网络钩子，然后点击 新建。

  2. 给网络钩子起一个清晰、有意义的名字，以明确其目的。

  3. 如果需要，并已激活开发者模式，请从下拉菜单中选择相应的 模型。如果未激活开发者模式，自动化规则默认以当前模型为目标。

  4. 网络钩子的 URL 会自动生成，但可根据需要通过点击 轮换密钥 进行更改。这是在外部系统中实施网络钩子时应使用的 URL，该系统将向数据库发送更新。

    警告

    此 URL 具有**机密性**，需谨慎处理。在网络上或不加防范地分享可能会导致意外访问 Odoo 数据库。如果 URL 在初始部署后有更新，请务必在外部系统中同步更新。

  5. 如需要，请启用 记录调用 以追踪向网络钩子的 URL 发送的 API 请求的历史记录，例如，用于故障排除。

  6. 如果发送网络钩子的系统并非 Odoo，请调整 :guilabel:`目标记录`的代码，使其能在 API 请求发送至网络钩子 URL 时，从有效负载中寻找相应的 JSON 记录。如果发送网络钩子的系统是 Odoo 数据库，请确保 id 和 model 出现在有效负载中。

    如果该网络钩子用于在 Odoo 数据库中创建记录，请使用 model.browse(i) 或 model.search(i)，而不是默认的 :guilabel:`目标记录`格式。

  7. 点击 待办操作 选项卡中的 添加操作 以定义要执行的 操作。

  8. 在外部系统中实施网络钩子之前，请 测试 以确保其按预期运行。

小技巧

  • 网络钩子也可通过**Studio**中的 :guilabel:`自动化`菜单选择触发器 :guilabel:`收到网络钩子时`来创建。

  • To access the history of API requests if Log Calls has been enabled, click the Logs smart button at the top of the Automation rules form.

  • If the purpose of the webhook is anything other than to update an existing record, e.g., to create a new record, the Execute Code action must be chosen.

Test a webhook

Testing a webhook requires a test payload and an external tool or system, like Postman, to send the payload via a POST API request. This section presents the steps to test a webhook in Postman.

小技巧

  • See the webhook use cases section for step-by-step explanations of how to test webhooks using test payloads.

  • To get specific help with testing a webhook with Postman, contact their support team.

  1. In Postman, create a new HTTP request and set its method to POST.

  2. Copy the webhook’s URL from your Odoo database using the (link) icon and paste it into the URL field in Postman.

  3. Click the Body tab and select raw.

  4. Set the file type to JSON, then copy the code from the test payload and paste it into the code editor.

  5. Click Send.

In the Response viewer at the bottom of the screen in Postman, details, including a HTTP response code, indicate whether or not the webhook is functioning correctly.

  • A 200 OK or status: ok message indicates that the webhook is functioning properly on Odoo’s side. From here, implementation can begin with the other system to automatically send the API requests to the Odoo webhook’s URL.

  • If any other response is returned, the number associated with it helps to identify the problem. For example, a 500 Internal Server Error message means that Odoo could not interpret the call properly. In this case, 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 in Odoo provides error logs if the webhook is not functioning as intended.

Implement a webhook in an external system

When the webhook has been successfully created in Odoo and tested, implement it in the system that sends data to the Odoo database, making sure the POST API requests are sent to the webhook’s URL.

Webhook use cases

Below are two examples of how to use webhooks in Odoo. A test payload is provided for each example, and can be found in the section on testing the webhook. Postman is used to send the test payload.

Update a sales order’s currency

This webhook updates a sales order in the Sales app to USD when the external system sends a POST API request to the webhook’s URL that includes that sales order number (which is identified by the payload’s id record).

This could be 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.

创建网络钩子

To create this webhook, proceed as follows:

  1. Open the Sales app, then open Studio and click Webhooks. The Sales Order model is selected by default.

  2. Click New. The Trigger is set to On webhook by default.

  3. 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 converts the retrieved id to an integer (i.e., a whole number) because the method browse() can only be used with an integer.

  4. 点击 添加操作。

  5. In the Type section, click Update Record.

  6. In the Action details section, select Update, choose the field Currency, and select USD.

  7. 点击 保存并关闭。

测试网络钩子

To test this webhook, proceed as follows:

  1. With Postman open, create a new HTTP request and set its method to POST.

  2. Copy the URL of the Odoo webhook using the (link) icon and paste it into the URL field in Postman.

  3. Click the Body tab and select raw.

  4. Set the file type to JSON, then copy this code, i.e., the payload, and paste it into the code editor:

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

  5. 在 Odoo 数据库中，选择一个销售订单来测试网络钩子。在粘贴的代码中，用销售订单的编号替换 销售订单编号，编号前不要有 S`或任何零。例如，编号为`S00007`的销售订单在 Postman 中应输入`7。

  6. Click Send.

  7. 查看 Postman 中的 回应查看器 以确定网络钩子是否正常运行。如果返回的信息不是 200 OK`或 `status: ok，则与信息相关的编号有助于确定问题所在。

新建联系人

This webhook uses custom code to create a new contact in an Odoo database when the external system sends a POST API request to the webhook’s URL that includes the contact’s information. This could be helpful for automatically creating new vendors or customers.

创建网络钩子

To create this webhook, proceed as follows:

  1. Open the Contacts app, then open Studio and click Webhooks. The Contact model is selected by default.

  2. Click New. The Trigger is set to On webhook by default.

  3. Set the Target Record to model.browse([2]). This is essentially a placeholder as the code in the automated action tells the webhook what needs to be retrieved from the payload and in which model the record needs to be created.

  4. 点击 添加操作。

  5. In the Type section, click Execute Code.

  6. Copy this code and paste it into the code editor in the Code tab of the Action details section:

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

  7. 点击 保存并关闭。

测试网络钩子

To test this webhook, proceed as follows:

  1. In Postman, create a new HTTP request and set its method to POST.

  2. Copy the URL of the Odoo webhook using the (link) icon and paste it into the URL field in Postman.

  3. Click the Body tab and select raw.

  4. Set the file type to JSON, then copy this code, i.e., the payload, and paste it into the code editor:

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

  5. In the pasted code, replace the CONTACT NAME, CONTACTEMAIL@EMAIL.COM, and CONTACT PHONE NUMBER with a new contact’s information.

  6. Click Send.

  7. 查看 Postman 中的 回应查看器 以确定网络钩子是否正常运行。如果返回的信息不是 200 OK`或 `status: ok，则与信息相关的编号有助于确定问题所在。