magpie.api.webhooks

Attributes

WEBHOOK_KEYS_REQUIRED
WEBHOOK_KEYS_OPTIONAL
WEBHOOK_KEYS
WEBHOOK_TEMPLATE_PARAMS
WEBHOOK_HTTP_METHODS
LOGGER
WebhookActionNames

Classes

WebhookAction

Supported Webhook actions.

Functions

get_permission_update_params(...)	Generates the Webhook parameters based on provided references.
process_webhook_requests(→ None)	Checks the config for any webhooks that correspond to the input action, and prepares corresponding requests.
generate_callback_url(→ magpie.typedefs.Str)	Generates a callback URL using Magpie temporary tokens for use by the webhook implementation.
replace_template(→ magpie.typedefs.WebhookPayload)	Replace each template parameter from the payload by its corresponding value.
send_webhook_request(→ None)	Sends a single webhook request using the input config.
webhook_update_error_status(→ None)	Updates the user's status to indicate an error occurred with the webhook requests.
setup_webhooks(→ None)	Prepares and validates Webhook settings for the application based on definitions in configuration file(s).

Module Contents

magpie.api.webhooks.WEBHOOK_KEYS_REQUIRED

magpie.api.webhooks.WEBHOOK_KEYS_OPTIONAL

magpie.api.webhooks.WEBHOOK_KEYS

magpie.api.webhooks.WEBHOOK_TEMPLATE_PARAMS = ['group.name', 'group.id', 'user.name', 'user.id', 'user.email', 'user.status', 'resource.id',...

magpie.api.webhooks.WEBHOOK_HTTP_METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']

magpie.api.webhooks.LOGGER

class magpie.api.webhooks.WebhookAction

Bases: magpie.utils.ExtendedEnum

Supported Webhook actions.

CREATE_USER = 'create_user'

Triggered when a new User gets successfully created.

See also

User Creation

DELETE_USER = 'delete_user'

Triggered when an existing User gets successfully deleted.

See also

User Deletion

UPDATE_USER_STATUS = 'update_user_status'

Triggered when an existing User status gets successfully updated.

See also

User Status Update

CREATE_USER_PERMISSION = 'create_user_permission'

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

See also

Permission Updates

DELETE_USER_PERMISSION = 'delete_user_permission'

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

See also

Permission Updates

CREATE_GROUP_PERMISSION = 'create_group_permission'

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

See also

Permission Updates

DELETE_GROUP_PERMISSION = 'delete_group_permission'

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

See also

Permission Updates

magpie.api.webhooks.WebhookActionNames

magpie.api.webhooks.get_permission_update_params(target: 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 Webhook parameters based on provided references.

magpie.api.webhooks.process_webhook_requests(action: WebhookAction, params: magpie.typedefs.WebhookTemplateParameters, update_user_status_on_error: bool = False, settings: magpie.typedefs.AnySettingsContainer | None = None) → None

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

Parameters:

• action – tag identifying which webhooks to use in the config

• 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.

• update_user_status_on_error – update the user status or not in case of a webhook error.

• settings – application settings where webhooks configuration can be retrieved.

magpie.api.webhooks.generate_callback_url(operation: magpie.models.TokenOperation, db_session: sqlalchemy.orm.session.Session, user: magpie.models.AnyUser | None = None, group: magpie.models.Group | None = None) → magpie.typedefs.Str

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

Parameters:

• operation – targeted operation that employs the callback URL for reference.

• db_session – database session to store the generated temporary token.

• user – user reference associated to the operation as applicable.

• group – group reference associated to the operation as applicable.

Returns:

generated callback URL.

magpie.api.webhooks.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.

Parameters:

• params – the values of the template parameters

• payload – structure containing the data to be processed by the template replacement

• force_str – enforce string conversion of applicable fields where non-string values are detected.

Returns:

structure containing the data with the replaced template parameters

magpie.api.webhooks.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.

Parameters:

• webhook_config – dictionary containing the config data of a single webhook

• params – dictionary containing the required parameters for the request, they will replace templates found in the payload

• update_user_status_on_error – update the user status or not in case of a webhook error

magpie.api.webhooks.webhook_update_error_status(user_name: magpie.typedefs.Str) → None

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

magpie.api.webhooks.setup_webhooks(config_path: magpie.typedefs.Str | None, settings: magpie.typedefs.SettingsType) → None

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

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

Any Webhook failing validation will raise the whole configuration and not apply any changes to the 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.

See also

Documentation in Webhook Configuration.

Parameters:

• config_path – a single file or directory path where configuration file(s) with webhook section.

• settings – modified settings in-place with added valid webhooks.