:py:mod:`magpie.api.webhooks`
=============================

.. py:module:: magpie.api.webhooks


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   magpie.api.webhooks.WebhookAction



Functions
~~~~~~~~~

.. autoapisummary::

   magpie.api.webhooks.get_permission_update_params
   magpie.api.webhooks.process_webhook_requests
   magpie.api.webhooks.generate_callback_url
   magpie.api.webhooks.replace_template
   magpie.api.webhooks.send_webhook_request
   magpie.api.webhooks.webhook_update_error_status
   magpie.api.webhooks.setup_webhooks



Attributes
~~~~~~~~~~

.. autoapisummary::

   magpie.api.webhooks.WEBHOOK_KEYS_REQUIRED
   magpie.api.webhooks.WEBHOOK_KEYS_OPTIONAL
   magpie.api.webhooks.WEBHOOK_KEYS
   magpie.api.webhooks.WEBHOOK_TEMPLATE_PARAMS
   magpie.api.webhooks.WEBHOOK_HTTP_METHODS
   magpie.api.webhooks.LOGGER
   magpie.api.webhooks.WebhookActionNames


.. py:data:: WEBHOOK_KEYS_REQUIRED

   

.. py:data:: WEBHOOK_KEYS_OPTIONAL

   

.. py:data:: WEBHOOK_KEYS

   

.. py:data:: WEBHOOK_TEMPLATE_PARAMS
   :value: ['group.name', 'group.id', 'user.name', 'user.id', 'user.email', 'user.status', 'resource.id',...

   

.. py:data:: WEBHOOK_HTTP_METHODS
   :value: ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']

   

.. py:data:: LOGGER

   

.. py:class:: WebhookAction


   Bases: :py:obj:`magpie.utils.ExtendedEnum`

   Supported :term:`Webhook` actions.

   .. py:attribute:: CREATE_USER
      :value: 'create_user'

      Triggered when a new :term:`User` gets successfully created.

      .. seealso::
          :ref:`webhook_user_create`


   .. py:attribute:: DELETE_USER
      :value: 'delete_user'

      Triggered when an existing :term:`User` gets successfully deleted.

      .. seealso::
          :ref:`webhook_user_delete`


   .. py:attribute:: UPDATE_USER_STATUS
      :value: 'update_user_status'

      Triggered when an existing :term:`User` status gets successfully updated.

      .. seealso::
          :ref:`webhook_user_update_status`


   .. py:attribute:: CREATE_USER_PERMISSION
      :value: 'create_user_permission'

      Triggered when a :term:`Permission` onto a :term:`Service` or :term:`Resource` gets created for a :term:`User`.

      .. seealso::
          :ref:`webhook_permission_updates`


   .. py:attribute:: DELETE_USER_PERMISSION
      :value: 'delete_user_permission'

      Triggered when a :term:`Permission` onto a :term:`Service` or :term:`Resource` gets deleted for a :term:`User`.

      .. seealso::
          :ref:`webhook_permission_updates`


   .. py:attribute:: CREATE_GROUP_PERMISSION
      :value: 'create_group_permission'

      Triggered when a :term:`Permission` onto a :term:`Service` or :term:`Resource` gets created for a :term:`Group`.

      .. seealso::
          :ref:`webhook_permission_updates`


   .. py:attribute:: DELETE_GROUP_PERMISSION
      :value: 'delete_group_permission'

      Triggered when a :term:`Permission` onto a :term:`Service` or :term:`Resource` gets deleted for a :term:`Group`.

      .. seealso::
          :ref:`webhook_permission_updates`



.. py:data:: WebhookActionNames

   

.. py:function:: get_permission_update_params(target: Union[magpie.models.User, magpie.models.Group], resource: magpie.typedefs.ServiceOrResourceType, permission: magpie.permissions.PermissionSet, db_session: sqlalchemy.orm.session.Session) -> magpie.typedefs.WebhookTemplateParameters

   Generates the :term:`Webhook` parameters based on provided references.


.. py:function:: process_webhook_requests(action: WebhookAction, params: magpie.typedefs.WebhookTemplateParameters, update_user_status_on_error: bool = False, settings: Optional[magpie.typedefs.AnySettingsContainer] = None) -> None

   Checks the config for any webhooks that correspond to the input action, and prepares corresponding requests.

   :param action: tag identifying which webhooks to use in the config
   :param params:
       Dictionary containing the required parameters and associated values for the request following the event action.
       Parameters will replace *templates* found in the ``payload`` definition of the webhook.
   :param update_user_status_on_error: update the user status or not in case of a webhook error.
   :param settings: application settings where webhooks configuration can be retrieved.


.. py:function:: generate_callback_url(operation: magpie.models.TokenOperation, db_session: sqlalchemy.orm.session.Session, user: Optional[magpie.models.AnyUser] = None, group: Optional[magpie.models.Group] = None) -> magpie.typedefs.Str

   Generates a callback URL using `Magpie` temporary tokens for use by the webhook implementation.

   :param operation: targeted operation that employs the callback URL for reference.
   :param db_session: database session to store the generated temporary token.
   :param user: user reference associated to the operation as applicable.
   :param group: group reference associated to the operation as applicable.
   :return: generated callback URL.


.. py:function:: replace_template(params: magpie.typedefs.WebhookTemplateParameters, payload: magpie.typedefs.WebhookPayload, force_str: bool = False) -> magpie.typedefs.WebhookPayload

   Replace each template parameter from the payload by its corresponding value.

   :param params: the values of the template parameters
   :param payload: structure containing the data to be processed by the template replacement
   :param force_str: enforce string conversion of applicable fields where non-string values are detected.
   :return: structure containing the data with the replaced template parameters


.. py:function:: send_webhook_request(webhook_config: magpie.typedefs.WebhookConfigItem, params: magpie.typedefs.WebhookTemplateParameters, update_user_status_on_error: bool = False) -> None

   Sends a single webhook request using the input config.

   :param webhook_config: dictionary containing the config data of a single webhook
   :param params: dictionary containing the required parameters for the request, they will replace templates
                   found in the payload
   :param update_user_status_on_error: update the user status or not in case of a webhook error


.. py:function:: webhook_update_error_status(user_name: magpie.typedefs.Str) -> None

   Updates the user's status to indicate an error occurred with the webhook requests.


.. py:function:: setup_webhooks(config_path: Optional[magpie.typedefs.Str], settings: magpie.typedefs.SettingsType) -> None

   Prepares and validates :term:`Webhook` settings for the application based on definitions in configuration file(s).

   Following execution, all validated :term:`Webhook` configurations will have every parameters defined in
   :py:data:`WEBHOOK_KEYS`, whether optional or mandatory. Required parameters in :py:data:`WEBHOOK_KEYS_REQUIRED`
   are explicitly validated for defined value and raise if missing. Parameters from :py:data:`WEBHOOK_KEYS_OPTIONAL`
   are defaulted to ``None`` if missing.

   Any :term:`Webhook` failing validation will raise the whole configuration and not apply any changes to
   the :paramref:`settings`. Format validation is applied to some specific parameters to anticipate and raise
   definitions guaranteed to be erroneous to avoid waiting until runtime for them to fail upon their trigger event.

   .. seealso::
       Documentation in :ref:`config_webhook`.

   :param config_path: a single file or directory path where configuration file(s) with ``webhook`` section.
   :param settings: modified settings in-place with added valid webhooks.