Open edX Webhooks #############################
|pypi-badge| |ci-badge| |codecov-badge| |doc-badge| |pyversions-badge| |license-badge| |status-badge|
Purpose
Webhooks for Open edX
This plugin implements a generic case of events handling that trigger a request to a configurable URL when a signal is received.
Getting Started
A Webhook
is a mechanism that triggers an HTTP POST request to a configurable
URL when certain events happen in the platform, including information relevant
to the event. For example, you can make the platform call an API when a user
logs in, including the user ID and email to connect to another application.
A Webfilter
is a special case of webhook that allows also modifying the
data and/or interrupting the process. For example, after the user login event
you can update the user full name or prevent the user to log in if it is not
allowed to.
To install this plugin into an Open edX installed by Tutor add this line
to the OPENEDX_EXTRA_PIP_REQUIREMENTS
list in the config.yml
file.
.. code-block::
OPENEDX_EXTRA_PIP_REQUIREMENTS:
- openedx-webhooks
If it is an existing installation, you might need to run migrations to create the database table. For this, run:
.. code-block::
tutor {dev|local|k8s} exec lms ./manage.py lms migrate
A new section named OPENEDX_WEBHOOKS
will be available in the LMS Django
admin site. It will contain two subsections: Webhooks
and Webfilters
.
Add a new webhook to define the URLs that will be called after each event is
received. More than one URL can be configured for each event. In this case,
all URLs will be called.
The Webhooks
Django admin panel has the following settings:
The Webfilters
Django admin panel has the following settings:
Both webhooks and webfilters will trigger POST requests to the configured URL.
This request includes in the payload a structure with data relevant to the
event that triggered the call. In all cases, the payload will include an
event_metadata
key including at least the event type and the date and time
in UTC format. Other keys included will depend on the event. For example,
log in events usually include user
and profile
keys with details of the
user logging in.
If the Use WWW form encoding
option is enabled, the data will be passed as
plain key-value pairs in form encoding. The structure will be flattened and the
key names will be concatenated. E.g., a log event will include user_id
,
user_email
, event_metadata_time
, etc.
The webhook processor should respond to a webfilter with a data structure in JSON format and a successful status code (200). The response can be empty or can have one or both of these keys:
Updating data
The corresponding objects will be updated with the values returned inside the
``data`` key. Only keys present in the response will be updated. Other keys
will remain unchanged in the original data structures. To disable data updates,
set ``Disable Filtering`` in the webfilter configuration at the Django admin
panel.
For example, to change the full name of a user at registration time, respond
to a `Student Registration Requested` webfilter with this data:
.. code-block::
{
"data": {
"form_data": {
"name": "New Name"
}
}
}
Interrupting execution
To stop the process to complete, add a JSON object as value for the exception
key. This object must have only one key-value pair, being the key the name
of the exception to raise. Its value can be either a string representing the
message to be shown, or another JSON object with more data.
For example, to prevent a user to register, respond to the Student Registration Requested
webfilter with this data:
.. code-block::
{
"exception": {
"PreventRegistration": "Not allowed to register"
}
}
To prevent a webfilter to stop the execution of the process, set Disable halting
in the webfilter configuration at the Django admin
panel.
Check each function documentation to see the list of available values and exceptions.
If you set more than one webhook or webfilter for the same event, all of them will be triggered. The responses of all the webfilters will be combined in one data structure and used to update the objects. If more webfilter processors include data for the same key, the last one will override all the previous.
More information about available signals can be found in the events documentation
and the filters documentation
.. _events documentation: https://github.com/openedx/edx-platform/blob/master/docs/guides/hooks/events.rst .. _filters documentation: https://github.com/openedx/edx-platform/blob/master/docs/guides/hooks/filters.rst
.. code-block::
git clone git@github.com:aulasneo/openedx-webhooks.git cd openedx-webhooks
mkvirtualenv -p python3.8 openedx-webhooks
.. code-block::
workon openedx-webhooks
git checkout main git pull
make requirements
make validate
git checkout -b
vim ...
pytest ./path/to/new/tests
make validate
git commit ... git push
Getting Help
If you need any help, send us an email to info@aulasneo.com
_.
.. _info@aulasneo.com: mailto:info@aulasneo.com
If you're having trouble, we have discussion forums at https://discuss.openedx.org where you can connect with others in the community.
Our real-time conversations are on Slack. You can request a Slack invitation
, then join our community Slack workspace
.
For anything non-trivial, the best path is to open an issue in this repository with as many details about the issue you are facing as you can provide.
https://github.com/aulasneo/openedx-webhooks/issues
For more information about these options, see the Getting Help
_ page.
.. _Slack invitation: https://openedx.org/slack .. _community Slack workspace: https://openedx.slack.com/ .. _Getting Help: https://openedx.org/getting-help
License
The code in this repository is licensed under the AGPL 3.0 unless otherwise noted.
Please see LICENSE.txt <LICENSE.txt>
_ for details.
Contributing
Contributions are very welcome.
Please read How To Contribute <https://openedx.org/r/how-to-contribute>
_ for details.
This project is currently accepting all types of contributions, bug fixes, security fixes, maintenance work, or new features. However, please make sure to have a discussion about your new feature idea with the maintainers prior to beginning development to maximize the chances of your change being accepted. You can start a conversation by creating a new issue on this repo summarizing your idea.
The Open edX Code of Conduct
All community members are expected to follow the Open edX Code of Conduct
_.
.. _Open edX Code of Conduct: https://openedx.org/code-of-conduct/
People
The assigned maintainers for this component and other project details may be
found in Backstage
_. Backstage pulls this data from the catalog-info.yaml
file in this repo.
.. _Backstage: https://backstage.openedx.org/catalog/default/component/webhooks
Reporting Security Issues
Please do not report security issues in public. Please email security@tcril.org.
.. |pypi-badge| image:: https://img.shields.io/pypi/v/webhooks.svg :target: https://pypi.python.org/pypi/webhooks/ :alt: PyPI
.. |ci-badge| image:: https://github.com/openedx/webhooks/workflows/Python%20CI/badge.svg?branch=main :target: https://github.com/openedx/webhooks/actions :alt: CI
.. |codecov-badge| image:: https://codecov.io/github/openedx/webhooks/coverage.svg?branch=main :target: https://codecov.io/github/openedx/webhooks?branch=main :alt: Codecov
.. |doc-badge| image:: https://readthedocs.org/projects/webhooks/badge/?version=latest :target: https://docs.openedx.org/projects/webhooks :alt: Documentation
.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/webhooks.svg :target: https://pypi.python.org/pypi/webhooks/ :alt: Supported Python versions
.. |license-badge| image:: https://img.shields.io/github/license/openedx/webhooks.svg :target: https://github.com/openedx/webhooks/blob/main/LICENSE.txt :alt: License
.. |status-badge| image:: https://img.shields.io/badge/Status-Experimental-yellow .. .. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen .. .. |status-badge| image:: https://img.shields.io/badge/Status-Deprecated-orange .. .. |status-badge| image:: https://img.shields.io/badge/Status-Unsupported-red