REST API for Webhook

API Logs

Every API call is logged under Settings > Technical > API Configuration > API Logs. Each log record shows:

• Request Preview / Response Preview - first N characters of the payload
• Request Size / Response Size - total character count
• Full Log button - opens the full JSON attachment when payload exceeds the preview limit
• Callback URL - URL stored from the inbound request for later outbound push

Authentication

Authenticate via /web/session/authenticate before calling any route:

{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "db": "<db_name>",
    "login": "<username>",
    "password": "<password>"
  }
}

Alternative - API Key: send Authorization: Bearer <api_key> on every request. No session call needed.

Relational Field Format

Multiple many2many items sharing the same lookup field are batched into a single DB query.

API Routes

{
  "params": {
    "model": "<model name>",
    "vals": {
      "callback_url": "https://your-system/webhook",
      "payload": {
        "<field1>": "<value1>",
        "<many2one_field_id>": {"name": "<value>"},
        "<many2many_field_ids>": {"mode": "replace", "records": [{"name": "<val1>"}]},
        "<one2many_field_ids>": [
          {"<field>": "<value>", "<nested_m2o_id>": {"name": "<value>"}}
        ]
      },
      "auto_create": {
        "<many2one_field_id>": {"name": "<value>"}
      },
      "result_field": ["<field1>"]
    }
  }
}

{
  "params": {
    "model": "<model name>",
    "vals": {
      "search_key": {"<key_field>": "<value>"},
      "payload": {
        "<field1>": "<value1>",
        "<many2one_field_id>": {"name": "<value>"}
      },
      "result_field": ["<field1>"]
    }
  }
}

{
  "params": {
    "model": "<model name>",
    "vals": {
      "search_key": {"<key_field>": "<value>"},
      "payload": {
        "<field1>": "<value1>",
        "<many2one_field_id>": {"id": 5},
        "<many2many_field_ids>": {"mode": "add", "records": [{"name": "<val1>"}]}
      },
      "result_field": ["<field1>"]
    }
  }
}

{
  "params": {
    "model": "<model name>",
    "vals": {
      "payload": {
        "search_field": [
          "<field1>",
          "<m2o_field>{<subfield1>,<subfield2>}",
          "<o2m_field>{<subfield1>}"
        ],
        "search_domain": "[('<field>', '<operator>', '<value>')]",
        "limit": 10,
        "order": "<field1> asc, <field2> desc"
      }
    }
  }
}

{
  "params": {
    "model": "account.move",
    "vals": {
      "search_key": {"id": 26},
      "payload": {
        "method": "action_post",
        "context": {"lang": "th_TH"}
      }
    }
  }
}

Attaching Files

Add attachment_ids at any payload level:

"attachment_ids": [{"name": "<filename>", "datas": "<base64>"}]

Step 1 - Add mixin to the target model

In any private addon, add one _inherit line:

from odoo import models

class SaleOrder(models.Model):
    _name = "sale.order"
    _inherit = ["sale.order", "webhook.outbound.mixin"]

All outbound behaviour is driven by rules configured in the UI.

Step 2 - Configure an Outbound Webhook Rule

Go to Settings > Technical > API Configuration > Outbound Webhook Rules. See CONFIGURE.md for the full field reference.

Trigger domain examples:

# Simple
[("state", "=", "sale")]

# Multiple conditions
[("state", "=", "done"), ("amount_total", ">", 100)]

# Multiple accepted values
[("state", "in", ["done", "validated"])]

The webhook fires only when a field in the domain is being written and the record matches the full domain after the write. This prevents re-triggering when unrelated fields are edited on an already-matching record.

Payload Fields

payload_fields is always a JSON object. Two kinds of values are supported:

• Static value (string, number, bool, nested object/array) - sent as-is
• ``{field.path}`` template - resolved from the triggering record (dotted paths supported, e.g. {partner_id.name}), returning the raw value at the end of the path. Templates are resolved recursively, so they can appear nested inside objects/arrays at any depth. A many2one field must be followed by an explicit subfield (e.g. {partner_id.name}) - {partner_id} alone returns the record itself, not its name.

{
  "request_code": "{name}",
  "app": "MyApp",
  "data": {"id": "{id}", "state": "{state}", "partner": "{partner_id.name}"}
}

Result posted to the external system:

{
  "request_code": "SO001",
  "app": "MyApp",
  "data": {"id": 3, "state": "sale", "partner": "ABC Co."}
}

Leave payload_fields empty to send {"id": <record_id>} only.

{
  "request_code": "{name}",
  "data": {
    "id": "{id}",
    "state": "{state}",
    "order_line": [
      {
        "product": "{product_id.name}",
        "qty": "{product_uom_qty}",
        "price": "{price_unit}"
      }
    ]
  }
}

{
  "request_code": "SO001",
  "data": {
    "id": 3,
    "state": "sale",
    "order_line": [
      {"product": "Product A", "qty": 2.0, "price": 500.0},
      {"product": "Product B", "qty": 1.0, "price": 300.0}
    ]
  }
}

Per-record Callback URL

Pass callback_url in the inbound create_data request. Odoo stores it linked to the created record. When the outbound rule fires with Endpoint Source = Record Callback URL, the system looks up that URL and POSTs to it.

{
  "params": {
    "model": "sale.order",
    "vals": {
      "callback_url": "https://ext-system/webhook/so-status",
      "payload": {
        "partner_id": {"name": "ABC Co."},
        "order_line": [{"product_id": {"name": "Product A"}, "product_uom_qty": 1}]
      }
    }
  }
}

When the SO is confirmed → Odoo automatically POSTs to https://ext-system/webhook/so-status.

Outbound Logs

All outbound calls appear in API Logs with Log Type = Send. Failed calls are marked state = failed with the error in the response preview.