openedx-webhooks 1.1.0

Webhooks for Open edX

Open edX Webhooks

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

Introduction

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.

Deploying

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.

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:

tutor {dev|local|k8s} exec lms ./manage.py lms migrate

Configuring

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.

Configuring webhooks

The Webhooks Django admin panel has the following settings:

• Description: Add a description for this webhook for reference.

• Event: Choose from the list the event that will trigger the webhook.

• Webhook URL: URL to call. Get it from your webhook processor.

• Enabled: Click to enable the webhook.

• Use WWW form encoding: When enabled, the data will be passed in a web form format. If disabled, data will be passed in JSON format.

Configuring webfilters

The Webfilters Django admin panel has the following settings:

• Description: Add a description for this webhook for reference.

• Event: Choose from the list the event that will trigger the webhook.

• Webhook URL: URL to call. Get it from your webhook processor.

• Enabled: Click to enable the webhook.

• Disable filtering: If enabled, the data passed to the web filter will not be modified even if the response includes any update.

• Disable halting: If enabled, the process will not be interrupted even if the response includes an exception setting.

• Halt on 4xx: Interrupt the process if the call to the URL returns any 4xx error code.

• Redirect on 4xx: Include an URL to redirect in case of a 4xx response, if the event supports redirection.

• Halt on 5xx: Interrupt the process if the call to the URL returns any 5xx error code.

• Redirect on 5xx: Include an URL to redirect in case of a 5xx response, if the event supports redirection.

• Halt on request exception: Interrupt the process if the call to the URL results in a connection error (e.g., timeout).

• Redirect on request exception: Include an URL to redirect in case of a connection error, if the event supports redirection.

• Use WWW form encoding: When enabled, the data will be passed in a web form format. If disabled, data will be passed in JSON format.

Receiving data

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.

Responding to webfilters

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:

• data

• exception

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:

{
    "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:

{
    "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.

Handling multiple events

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.

Developing

More information about available signals can be found in the events documentation and the filters documentation

One Time Setup

# Clone the repository
git clone [e-mail]:aulasneo/openedx-webhooks.git
cd openedx-webhooks

# Set up a virtualenv with the same name as the repo and activate it
# Here's how you might do that if you have virtualenvwrapper setup.
mkvirtualenv -p python3.8 openedx-webhooks

Every time you develop something in this repo

# Activate the virtualenv
# Here's how you might do that if you're using virtualenvwrapper.
workon openedx-webhooks

# Grab the latest code
git checkout main
git pull

# Install/update the dev requirements
make requirements

# Run the tests and quality checks (to verify the status before you make any changes)
make validate

# Make a new branch for your changes
git checkout -b <your_github_username>/<short_description>

# Using your favorite editor, edit the code to make your change.
vim ...

# Run your new tests
pytest ./path/to/new/tests

# Run all the tests and quality checks
make validate

# Commit all your changes
git commit ...
git push

# Open a PR and ask for review.

Getting Help

If you need any help, send us an email to [e-mail].

More Help

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.

License

The code in this repository is licensed under the AGPL 3.0 unless otherwise noted.

Please see LICENSE.txt for details.

Contributing

Contributions are very welcome. Please read 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.

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.

Reporting Security Issues

Please do not report security issues in public. Please email [e-mail].

Change Log

Version 1.1.0 (2023-08-22)

• Add grade changes signals

  • COURSE_GRADE_CHANGED

  • COURSE_GRADE_NOW_PASSED

  • COURSE_GRADE_NOW_FAILED

Version 1.0.1 (2023-08-15)

• Fix: remove non implemented filters

Version 1.0.0 (2023-08-15)

• Added webfilters:

  • CertificateCreationRequested,

  • CertificateRenderStarted,

  • CohortAssignmentRequested,

  • CohortChangeRequested,

  • CourseAboutRenderStarted,

  • CourseEnrollmentStarted,

  • CourseUnenrollmentStarted,

  • DashboardRenderStarted,

  • StudentLoginRequested,

  • StudentRegistrationRequested,

• Available webhooks:

  • SESSION_LOGIN_COMPLETED

  • STUDENT_REGISTRATION_COMPLETED

  • COURSE_ENROLLMENT_CREATED

  • COURSE_ENROLLMENT_CHANGED

  • COURSE_UNENROLLMENT_COMPLETED

  • CERTIFICATE_CREATED

  • CERTIFICATE_CHANGED

  • CERTIFICATE_REVOKED

  • COHORT_MEMBERSHIP_CHANGED

  • COURSE_DISCUSSIONS_CHANGED

Version 0.2.1 (2023-06-06)

• Renamed package to openedx_webhooks. Upload to PyPI.

Version 0.1.1 (2023-06-05)

• Improve documentation

0.1.0 – 2023-05-31

Added

• First release on PyPI.