====================
Cetmix Tower Webhook
====================

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:6b28bb3bec0ce3e160c08d87fdf2735a4ca2fc271dbf3e361152240f0f02437c
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
    :target: https://odoo-community.org/page/development-status
    :alt: Beta
.. |badge2| image:: https://img.shields.io/badge/license-AGPL--3-blue.png
    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
    :alt: License: AGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-cetmix%2Fcetmix--tower-lightgray.png?logo=github
    :target: https://github.com/cetmix/cetmix-tower/tree/16.0/cetmix_tower_webhook
    :alt: cetmix/cetmix-tower

|badge1| |badge2| |badge3|

This module implements incoming webhooks for `Cetmix
Tower <https://tower.cetmix.com>`__. Webhooks are authorised using
customisable authenticators which can be pre-configured and reused
across multiple webhooks. Webhooks and authenticators can be exported
and imported using YAML format, which makes them easily sharable.

This module is a part of Cetmix Tower, however it can be used to manage
any other odoo applications.

Please refer to the `official
documentation <https://tower.cetmix.com>`__ for detailed information.

**Table of contents**

.. contents::
   :local:

Use Cases / Context
===================

Although Odoo has native support of webhooks staring 17.0, they still
have some limitations. Another option is the OCA 'endpoint' module which
although is more flexible still makes it usable with Cetmix Tower more
complicated.

Configuration
=============

Configure an Authenticator
--------------------------

**⚠️ WARNING: You must be a member of the "Cetmix Tower/Root" group to
configure authenticators.**

- Go to "Cetmix Tower > Settings > Automation > Webhook Authenticators"
  and click "New".

**Complete the following fields:**

- Name. Authenticator name
- Reference. Unique reference. Leave this field blank to auto generate
  it
- Code. Code that is used to authenticate the request. You can use all
  Cetmix Tower - Python command variables except for the server​ plus the
  following webhook specific ones:
- headers: dictionary that contains the request headers
- raw_data: string with the raw HTTP request body
- payload: dictionary that contains the JSON payload or the GET
  parameters of the request

**The code returns the result​ variable in the following format:**

.. code:: python

   result = {"allowed": <bool, mandatory, default=False>, "http_code": <int, optional>, "message": <str, optional>}

eg:

.. code:: python

   result = {"allowed": True}
   result = {"allowed": False, "http_code": 403, "message": "Sorry..."}

Configure a Webhook
-------------------

**⚠️ WARNING: You must be a member of the "Cetmix Tower/Root" group to
configure webhooks.**

- Go to "Cetmix Tower > Settings > Automation > Webhooks" and click
  "New".

**Complete the following fields:**

- Enabled. Uncheck this field to disable the webhook without deleting it
- Name. Authenticator name
- Reference. Unique reference. Leave this field blank to auto generate
  it
- Authenticator. Select an Authenticator used for this webhook
- Endpoint. Webhook andpoint. The complete webhook URL will be
  <your_tower_url>/cetmix_tower_webhooks/​
- Run as User. Select a user to run the webhook on behalf of. CAREFUL!
  You must realize and understand what you are doing, including all the
  possible consequences when selecting a specific user.
- Code. Code that processes the request. You can use all Cetmix Tower
  Python command variables (except for the server) plus the following
  webhook-specific one:

  - headers: dictionary that contains the request headers
  - payload: dictionary that contains the JSON payload or the GET
    parameters of the request

Webhook code returns a result using the Cetmix Tower Python command
pattern:

.. code:: python

   result = {"exit_code": <int, default=0>, "message": <string, default=None}

**To configure the time for which the webhook call logs are stored:**

- Go to "Cetmix Tower > Settings > General Settings"
- Put a number of days into the "Keep Webhook Logs for (days)" field.
  Default value is 30.

Please refer to the `official
documentation <https://tower.cetmix.com>`__ for detailed configuration
instructions.

Usage
=====

When a request is received, Cetmix Tower will search for the webhook
with the matching endpoint and authenticate the request using the
selected authenticator. In case of successful authentication webhook
code is run. Each webhook call is logged. Logs are available under the
"Cetmix Tower > Logs > Webhook Calls" menu or under the "Logs" button
directly in the Webhook.

Please refer to the `official
documentation <https://tower.cetmix.com>`__ for detailed usage
instructions.

Changelog
=========

16.0.1.0.4 (2025-12-11)
-----------------------

- Features: Improve search views, implement the search panel for
  selected views. (5139)

16.0.1.0.3 (2025-10-21)
-----------------------

- Features: Use native functions to convert payload to dict (5024)

16.0.1.0.2 (2025-10-06)
-----------------------

- Bugfixes: Export related variables and secrets (4980)

Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/cetmix/cetmix-tower/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/cetmix/cetmix-tower/issues/new?body=module:%20cetmix_tower_webhook%0Aversion:%2016.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
-------

* Cetmix

Maintainers
-----------

This module is part of the `cetmix/cetmix-tower <https://github.com/cetmix/cetmix-tower/tree/16.0/cetmix_tower_webhook>`_ project on GitHub.

You are welcome to contribute.
