Webhooks link

:::: warning ::: title 警告 :::

强烈建议在决定使用 Webhook 并在整个实现过程中，咨询开发者、解决方案架构师或其他技术角色。如果配置不当，Webhook 可能会扰乱 Odoo 数据库，且恢复可能需要时间。 ::::

Webhook 可以在 Odoo Studio 中创建，它允许在另一个外部系统发生特定事件时，在你的 Odoo 数据库中自动执行操作。

实际工作原理如下：当外部系统中发生事件时，数据文件（即 “payload”）通过 [POST] API 请求发送到 Odoo Webhook 的 URL，并在你的 Odoo 数据库中执行预定义的操作。

与在预定间隔运行的计划动作或需要显式调用的手动 API 请求不同，Webhook 实现了实时、事件驱动的通信和自动化。例如，你可以设置一个 Webhook，使 Odoo 库存数据在外部 POS 系统确认销售订单时自动更新。

在 Odoo 中设置 Webhook 连接两个 Odoo 数据库时无需编写代码，但 测试 Webhook <studio/webhooks/test-webhook> 需要外部工具。 自定义目标记录或动作 <studio/webhooks/webhook-example> 可能需要编程技能。

:::: note ::: title 注意 :::

本文覆盖了创建一个 接收 来自外部源数据的 Webhook。但同样可以创建一个自动化动作，在 Odoo 数据库发生变化时 向外部 Webhook 发送数据 <studio/automated-actions/action-webhook>。 ::::

在 Odoo 中创建 Webhook {#studio/webhooks/create-webhook} link

:::: important ::: title 重要 :::

在真实数据库中实现 Webhook 前，请使用 复制数据库 <odoo-online/duplicate> 进行配置和测试，以确保 Webhook 按预期工作。 ::::

:::: tip ::: title 提示 :::

在创建 Webhook 前 激活开发者模式 <developer-mode> 可让你在选择 模型 <../models_modules_apps> 时拥有更大灵活性。它还能帮助你找到模型和字段的技术名称，这可能在配置 payload 时需要。

要查找模型的技术名称，激活开发者模式后，将鼠标悬停在模型名称上，然后点击 fa-arrow-right (内部链接)。技术名称显示在 Model 字段中。例如，销售订单的 Webhook 使用 Sales Order 模型，但 payload 中使用的是技术名称 [sale.order]。 ::::

在 Studio 中创建 Webhook，按以下步骤操作：

1. 打开 Studio <studio/access>，点击 Webhooks，随后点击 New。

2. 为 Webhook 起一个清晰、能体现其用途的名称。

3. 如有需要且已激活开发者模式，从下拉框中选择相应的 Model。若未激活开发者模式，自动规则默认针对当前模型。

4. Webhook 的 URL 会自动生成，若需要可点击 Rotate Secret 更改。此 URL 应在外部系统实现 Webhook 时使用，以向数据库发送更新。

   :::: warning ::: title 警告 :::

   此 URL 机密，请谨慎对待。在线或不慎共享可能导致未授权访问 Odoo 数据库。若在初始实现后更新了 URL，请务必在外部系统中同步更新。 ::::

5. 如有需要，启用 Log Calls 以记录对 Webhook URL 的 API 请求历史，便于故障排查。

6. 若发送 Webhook 的系统不是 Odoo，请调整 Target Record 代码，使其在 API 请求到达 Webhook URL 时查找 payload 中的 JSON 记录。若发送系统为 Odoo 数据库，请确保 payload 中出现 [id] 与 [model]。

   若 Webhook 用于在 Odoo 数据库中创建记录，请使用 [model.browse(i)] 或 [model.search(i)] 替代默认的 Target Record 格式。

7. 在 Actions To Do 选项卡中点击 Add an action，定义要执行的 actions <studio/automated-actions/action>。

8. 在将 Webhook 部署到外部系统前，测试 <studio/webhooks/test-webhook> 以确保其工作正常。

:::: tip ::: title 提示 :::

• 也可以在 Studio 的 Automations 菜单中选择触发器 On webhook 来创建 Webhook。
• 若已启用 Log Calls，点击 Automation rules 表单顶部的 Logs 智能按钮即可查看 API 请求历史。
• 若 Webhook 的目的不是更新已有记录，而是创建新记录，则必须选择 Execute Code 动作。 ::::

测试 Webhook {#studio/webhooks/test-webhook} link

测试 Webhook 需要一个测试 payload 和外部工具（如 Postman）通过 [POST] API 请求发送 payload。本节介绍在 Postman 中测试 Webhook 的步骤。

:::: tip ::: title 提示 :::

• 请参阅 Webhook 用例章节 <studio/webhooks/webhook-examples>，获取使用测试 payload 测试 Webhook 的逐步说明。
• 若需针对 Postman 的具体帮助，请联系其支持团队。 ::::

1. 在 Postman 中创建一个新的 HTTP 请求，并将方法设为 POST。
2. 使用 fa-link (链接) 图标复制 Odoo 数据库中 Webhook 的 URL，粘贴到 Postman 的 URL 栏。
3. 点击 Body 选项卡，选择 raw。
4. 将文件类型设为 JSON，然后复制测试 payload 的代码粘贴到代码编辑器。
5. 点击 Send。

::: {#studio/webhooks/test-webhook-response} 在 Postman 界面底部的 Response 查看器中，会显示包括 HTTP 响应码在内的细节，以判断 Webhook 是否正常工作。 :::

• 返回 [200 OK] 或 [status: ok] 表示 Webhook 在 Odoo 端运行正常，随后即可在外部系统中实现自动发送 API 请求至 Odoo Webhook URL。
• 其他响应码则帮助定位问题。例如 [500 Internal Server Error] 表示 Odoo 未能正确解析调用，此时请确认 JSON 文件中的字段在 Webhook 配置及发送系统中已正确映射。

:::: tip ::: title 提示 :::

在 Odoo 中的 Webhook 配置中开启调用日志，可在出现异常时获取错误日志。 ::::

在外部系统中实现 Webhook link

当 Webhook 在 Odoo 中成功创建并通过测试后，在发送数据至 Odoo 数据库的系统中实现它，确保将 [POST] API 请求发送到 Webhook 的 URL。

Webhook 用例 {#studio/webhooks/webhook-examples} link

以下提供两个在 Odoo 中使用 Webhook 的示例。每个示例均附有测试 payload，可在测试章节中找到。使用 Postman 发送测试 payload。

更新销售订单的货币 link

此 Webhook 在外部系统向 Webhook URL 发送包含销售订单编号的 [POST] API 请求时，将 Sales 应用中的销售订单货币更新为 [USD]。

该功能对位于美国之外的子公司或在合并时将数据统一到同一 Odoo 数据库的场景非常有用。

创建 Webhook link

1. 打开 Sales 应用，打开 Studio <studio/access>，点击 Webhooks。默认已选中 Sales Order 模型。
2. 点击 New。Trigger 默认已设为 On webhook。
3. 将 Target Record 设为
   [model.env[payload.get('_model')].browse(int(payload.get('_id')))]，其中：
   • payload.get('_model') 获取 payload 中 model 键对应的值，即 [sale.order]（Sales Order 模型的技术名称）。
   • payload.get('_id') 获取 payload 中 id 键对应的值，即目标销售订单在 Odoo 中的编号（去除前导的 S 与零）。
   • int 将获取的 id 转为整数，因为 browse() 只能接受整数。
4. 点击 Add an action。
5. 在 Type 部分，选择 Update Record。
6. 在 Action details 中，选择 Update，字段设为 Currency，值设为 USD。
7. 点击 Save & Close。

测试 Webhook link

1. 在 Postman 中新建 HTTP 请求，方法设为 POST。

2. 使用 fa-link 图标复制 Odoo Webhook 的 URL，粘贴到 Postman。

3. 进入 Body → raw，文件类型设为 JSON，粘贴以下代码：

   {
       "_model": "sale.order",
       "_id": "SALES ORDER NUMBER"
   }

4. 在 Odoo 数据库中选取一个销售订单进行测试。将代码中的 [SALES ORDER NUMBER] 替换为该订单的数字编号（去掉前面的 S 与零），例如 [S00007] 应写成 7。

5. 点击 Send，在 Postman 的 Response viewer 中查看是否返回 [200 OK] 或 [status: ok]。若返回其他信息，请根据响应码定位问题。

创建新联系人 {#studio/webhooks/webhook-example} link

此 Webhook 使用自定义代码，在外部系统向 Webhook URL 发送包含联系人信息的 [POST] API 请求时，在 Odoo 数据库中创建新联系人。适用于自动创建供应商或客户。

创建 Webhook link

1. 打开 Contacts 应用，打开 Studio <studio/access>，点击 Webhooks。默认已选中 Contact 模型。

2. 点击 New，Trigger 默认已设为 On webhook。

3. 将 Target Record 设为 [model.browse([2])]，这仅是占位符，实际记录由代码从 payload 中获取并在相应模型中创建。

4. 点击 Add an action。

5. 在 Type 部分选择 Execute Code。

6. 将以下代码复制并粘贴到 Code 选项卡的代码编辑器中：

   # 从 payload 中获取并保存数据的变量
   contact_name = payload.get('name')
   contact_email = payload.get('email')
   contact_phone = payload.get('phone')
   
   # 将变量转化为 Odoo 联系人的 Python 函数
   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,
       })
   else:
       raise ValueError("Missing required fields: 'name' and 'email'")

7. 点击 Save & Close。

测试 Webhook link

1. 在 Postman 中新建 HTTP 请求，方法设为 POST。

2. 使用 fa-link 图标复制 Odoo Webhook 的 URL，粘贴到 Postman。

3. 进入 Body → raw，文件类型设为 JSON，粘贴以下代码：

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

4. 将 [CONTACT NAME]、[CONTACTEMAIL@EMAIL.COM]、[CONTACT PHONE NUMBER] 替换为新联系人的实际信息。

5. 点击 Send，在 Postman 的 Response viewer 中检查是否返回 [200 OK] 或 [status: ok]，否则根据响应码排查问题。